@ecopages/browser-router 0.2.0-alpha.5 → 0.2.0-alpha.6

package/src/client/eco-router.ts

@@ -4,6 +4,12 @@
  */
 
 import type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './types.ts';
+import { getEcoNavigationRuntime } from '@ecopages/core/router/navigation-coordinator';
+import {
+	getAnchorFromNavigationEvent,
+	recoverPendingNavigationHref,
+	type EcoPendingNavigationIntent,
+} from '@ecopages/core/router/link-intent';
 import { DEFAULT_OPTIONS } from './types.ts';
 import { DomSwapper, ScrollManager, ViewTransitionManager, PrefetchManager } from './services/index.ts';
 
@@ -13,7 +19,12 @@ import { DomSwapper, ScrollManager, ViewTransitionManager, PrefetchManager } fro
  */
 export class EcoRouter {
 	private options: Required<EcoRouterOptions>;
-	private abortController: AbortController | null = null;
+	private unregisterNavigationRuntime: (() => void) | null = null;
+	private started = false;
+	private pendingNavigations = 0;
+	private pendingPointerNavigation: EcoPendingNavigationIntent | null = null;
+	private pendingHoverNavigation: EcoPendingNavigationIntent | null = null;
+	private queuedNavigationHref: string | null = null;
 
 	private domSwapper: DomSwapper;
 	private scrollManager: ScrollManager;
@@ -35,9 +46,216 @@ export class EcoRouter {
 		}
 
 		this.handleClick = this.handleClick.bind(this);
+		this.handleHoverIntent = this.handleHoverIntent.bind(this);
+		this.handlePointerDown = this.handlePointerDown.bind(this);
 		this.handlePopState = this.handlePopState.bind(this);
 	}
 
+	private getLinkFromEvent(event: MouseEvent | PointerEvent): HTMLAnchorElement | null {
+		return getAnchorFromNavigationEvent(event, this.options.linkSelector);
+	}
+
+	private canInterceptLink(event: MouseEvent | PointerEvent, link: HTMLAnchorElement): string | null {
+		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return null;
+		if (event.button !== 0) return null;
+
+		const target = link.getAttribute('target');
+		if (target && target !== '_self') return null;
+
+		if (link.hasAttribute(this.options.reloadAttribute)) return null;
+		if (link.hasAttribute('download')) return null;
+
+		const href = link.getAttribute('href');
+		if (!href) return null;
+
+		if (href.startsWith('#')) return null;
+		if (href.startsWith('javascript:')) return null;
+
+		const url = new URL(href, window.location.origin);
+		if (!this.isSameOrigin(url)) return null;
+
+		return href;
+	}
+
+	private getRecoveredPointerHref(): string | null {
+		const href = recoverPendingNavigationHref(
+			this.pendingPointerNavigation,
+			this.pendingNavigations > 0,
+			performance.now(),
+		);
+
+		if (!href) {
+			this.pendingPointerNavigation = null;
+		}
+
+		return href;
+	}
+
+	private getRecoveredHoverHref(): string | null {
+		const href = recoverPendingNavigationHref(
+			this.pendingHoverNavigation,
+			this.pendingNavigations > 0,
+			performance.now(),
+		);
+
+		if (!href) {
+			this.pendingHoverNavigation = null;
+		}
+
+		return href;
+	}
+
+	private isAnotherNavigationRuntimeActive(): boolean {
+		const ownerState = getEcoNavigationRuntime(window).getOwnerState();
+		return (
+			ownerState.owner !== 'none' && ownerState.owner !== 'browser-router' && ownerState.canHandleSpaNavigation
+		);
+	}
+
+	private getDocumentOwner(doc: Document) {
+		return getEcoNavigationRuntime(window).resolveDocumentOwner(doc, 'browser-router');
+	}
+
+	private adoptDocumentOwner(doc: Document): void {
+		getEcoNavigationRuntime(window).adoptDocumentOwner(doc, 'browser-router');
+	}
+
+	private syncDocumentElementAttributes(newDocument: Document): void {
+		const currentHtml = document.documentElement;
+		const nextHtml = newDocument.documentElement;
+
+		for (const attribute of Array.from(currentHtml.attributes)) {
+			if (!nextHtml.hasAttribute(attribute.name)) {
+				currentHtml.removeAttribute(attribute.name);
+			}
+		}
+
+		for (const attribute of Array.from(nextHtml.attributes)) {
+			if (currentHtml.getAttribute(attribute.name) !== attribute.value) {
+				currentHtml.setAttribute(attribute.name, attribute.value);
+			}
+		}
+	}
+
+	private reloadDocument(url: URL): void {
+		window.location.assign(url.href);
+	}
+
+	/**
+	 * Commits a fully fetched document into the live page.
+	 *
+	 * When browser-router accepts a handoff from another runtime, it delays source
+	 * runtime cleanup until the incoming document has been prepared and is ready to
+	 * commit. That ordering avoids the blank-page window we previously hit when a
+	 * delegated navigation went stale after the source runtime had already torn
+	 * itself down.
+	 */
+	private async commitDocumentNavigation(
+		url: URL,
+		direction: EcoNavigationEvent['direction'],
+		newDocument: Document,
+		options: {
+			html?: string;
+			isStaleNavigation?: () => boolean;
+		} = {},
+	): Promise<void> {
+		const previousUrl = new URL(window.location.href);
+		const navigationRuntime = getEcoNavigationRuntime(window);
+		const isStaleNavigation = options.isStaleNavigation ?? (() => false);
+		const currentDocumentOwner = navigationRuntime.resolveDocumentOwner(document, 'browser-router');
+		const newDocumentOwner = navigationRuntime.resolveDocumentOwner(newDocument, 'browser-router');
+		const activeOwner = navigationRuntime.getOwnerState().owner;
+		const shouldCleanupCurrentOwner =
+			currentDocumentOwner !== newDocumentOwner &&
+			currentDocumentOwner !== 'browser-router' &&
+			activeOwner === currentDocumentOwner;
+		let shouldReload = false;
+		const beforeSwapEvent: EcoBeforeSwapEvent = {
+			url,
+			direction,
+			newDocument,
+			reload: () => {
+				shouldReload = true;
+			},
+		};
+
+		document.dispatchEvent(new CustomEvent('eco:before-swap', { detail: beforeSwapEvent }));
+		if (isStaleNavigation()) return;
+
+		if (shouldReload) {
+			if (shouldCleanupCurrentOwner) {
+				await navigationRuntime.cleanupOwner(currentDocumentOwner);
+			}
+			if (isStaleNavigation()) return;
+			this.reloadDocument(url);
+			return;
+		}
+
+		const useViewTransitions = this.options.viewTransitions;
+		await this.domSwapper.preloadStylesheets(newDocument);
+		if (isStaleNavigation()) return;
+
+		// Defer source-runtime cleanup until the incoming document is ready to win.
+		if (shouldCleanupCurrentOwner) {
+			await navigationRuntime.cleanupOwner(currentDocumentOwner);
+		}
+
+		if (isStaleNavigation()) return;
+
+		const commitSwap = () => {
+			if (isStaleNavigation()) return;
+
+			if (this.options.updateHistory && direction === 'forward') {
+				window.history.pushState({}, '', url.href);
+			} else if (direction === 'replace') {
+				window.history.replaceState({}, '', url.href);
+			}
+
+			this.syncDocumentElementAttributes(newDocument);
+			this.domSwapper.morphHead(newDocument);
+			if (useViewTransitions && !this.domSwapper.shouldReplaceBodyForRerunScripts()) {
+				this.domSwapper.morphBody(newDocument);
+			} else {
+				this.domSwapper.replaceBody(newDocument);
+			}
+			this.domSwapper.flushRerunScripts();
+			this.scrollManager.handleScroll(url, previousUrl);
+		};
+
+		if (useViewTransitions) {
+			await this.viewTransitionManager.transition(commitSwap);
+		} else {
+			commitSwap();
+		}
+
+		if (isStaleNavigation()) return;
+
+		navigationRuntime.adoptDocumentOwner(newDocument, 'browser-router');
+
+		const afterSwapEvent: EcoAfterSwapEvent = {
+			url,
+			direction,
+		};
+
+		document.dispatchEvent(new CustomEvent('eco:after-swap', { detail: afterSwapEvent }));
+
+		this.prefetchManager?.observeNewLinks();
+
+		if (options.html) {
+			this.prefetchManager?.cacheVisitedPage(url.href, options.html);
+		}
+
+		requestAnimationFrame(() => {
+			if (isStaleNavigation()) return;
+
+			document.dispatchEvent(
+				new CustomEvent('eco:page-load', {
+					detail: { url, direction } as EcoNavigationEvent,
+				}),
+			);
+		});
+	}
+
 	/**
 	 * Starts the router and begins intercepting navigation.
 	 *
@@ -45,27 +263,66 @@ export class EcoRouter {
 	 * back/forward buttons. Also starts the prefetch manager if configured.
 	 */
 	public start(): void {
-		document.addEventListener('click', this.handleClick);
+		if (this.started) {
+			return;
+		}
+
+		const navigationRuntime = getEcoNavigationRuntime(window);
+
+		document.addEventListener('mouseover', this.handleHoverIntent, true);
+		document.addEventListener('pointerover', this.handleHoverIntent, true);
+		document.addEventListener('mousemove', this.handleHoverIntent, true);
+		document.addEventListener('pointermove', this.handleHoverIntent, true);
+		document.addEventListener('pointerdown', this.handlePointerDown, true);
+		document.addEventListener('click', this.handleClick, true);
 		window.addEventListener('popstate', this.handlePopState);
 		this.prefetchManager?.start();
+		this.unregisterNavigationRuntime?.();
+		this.unregisterNavigationRuntime = navigationRuntime.register({
+			owner: 'browser-router',
+			navigate: async (request) => {
+				await this.performNavigation(
+					new URL(request.href, window.location.origin),
+					request.direction ?? 'forward',
+				);
+				return true;
+			},
+			handoffNavigation: async (request) => {
+				const { isStaleNavigation, complete } = this.beginNavigationTransaction();
+				if (isStaleNavigation()) return true;
+				try {
+					await this.commitDocumentNavigation(
+						new URL(request.finalHref ?? request.href, window.location.origin),
+						request.direction ?? 'forward',
+						request.document,
+						{ html: request.html, isStaleNavigation },
+					);
+				} finally {
+					complete();
+				}
+				return true;
+			},
+			reloadCurrentPage: async (request) => {
+				if (this.pendingNavigations > 0) return;
 
-		const windowWithHmr = window as typeof window & {
-			__ecopages_reload_current_page__?: (options: { clearCache: boolean }) => Promise<void>;
-		};
-
-		windowWithHmr.__ecopages_reload_current_page__ = async (options: { clearCache: boolean }) => {
-			const currentUrl = window.location.pathname + window.location.search;
+				const currentUrl = window.location.pathname + window.location.search;
 
-			if (options.clearCache) {
-				this.prefetchManager?.invalidate(currentUrl);
-			}
+				if (request?.clearCache) {
+					this.prefetchManager?.invalidate(currentUrl);
+				}
 
-			await this.performNavigation(new URL(currentUrl, window.location.origin), 'replace');
-		};
+				await this.performNavigation(new URL(currentUrl, window.location.origin), 'replace');
+			},
+			cleanupBeforeHandoff: async () => {
+				this.cancelNavigationTransaction();
+			},
+		});
+		this.adoptDocumentOwner(document);
 
 		// Cache the initial page for instant back-navigation
 		const initialHtml = document.documentElement.outerHTML;
 		this.prefetchManager?.cacheVisitedPage(window.location.href, initialHtml);
+		this.started = true;
 	}
 
 	/**
@@ -73,15 +330,30 @@ export class EcoRouter {
 	 * After calling this, navigation will fall back to full page reloads.
 	 */
 	public stop(): void {
-		document.removeEventListener('click', this.handleClick);
+		if (!this.started) {
+			return;
+		}
+
+		this.cancelNavigationTransaction();
+		document.removeEventListener('mouseover', this.handleHoverIntent, true);
+		document.removeEventListener('pointerover', this.handleHoverIntent, true);
+		document.removeEventListener('mousemove', this.handleHoverIntent, true);
+		document.removeEventListener('pointermove', this.handleHoverIntent, true);
+		document.removeEventListener('pointerdown', this.handlePointerDown, true);
+		document.removeEventListener('click', this.handleClick, true);
 		window.removeEventListener('popstate', this.handlePopState);
 		this.prefetchManager?.stop();
-
-		const windowWithHmr = window as typeof window & {
-			__ecopages_reload_current_page__?: (options: { clearCache: boolean }) => Promise<void>;
-		};
-
-		windowWithHmr.__ecopages_reload_current_page__ = undefined;
+		this.unregisterNavigationRuntime?.();
+		this.unregisterNavigationRuntime = null;
+		this.started = false;
+		this.pendingHoverNavigation = null;
+		this.pendingPointerNavigation = null;
+		this.queuedNavigationHref = null;
+
+		const win = window as RouterWindow;
+		if (win[ACTIVE_ROUTER_KEY] === this) {
+			delete win[ACTIVE_ROUTER_KEY];
+		}
 	}
 
 	/**
@@ -123,35 +395,77 @@ export class EcoRouter {
 	 * Uses `event.composedPath()` to correctly detect clicks on anchors inside
 	 * Shadow DOM boundaries (Web Components).
 	 */
-	private handleClick(event: MouseEvent): void {
-		const link = event
-			.composedPath()
-			.find(
-				(el) => el instanceof HTMLAnchorElement && el.matches(this.options.linkSelector),
-			) as HTMLAnchorElement | null;
+	private handlePointerDown(event: PointerEvent): void {
+		const link = this.getLinkFromEvent(event);
+		if (!link) {
+			this.pendingPointerNavigation = null;
+			return;
+		}
 
-		if (!link) return;
+		const href = this.canInterceptLink(event, link);
+		this.pendingPointerNavigation = href
+			? {
+					href,
+					timestamp: performance.now(),
+				}
+			: null;
 
-		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
-		if (event.button !== 0) return;
+		if (href && this.pendingNavigations > 0) {
+			this.queuedNavigationHref = href;
+		}
+	}
 
-		const target = link.getAttribute('target');
-		if (target && target !== '_self') return;
+	private handleHoverIntent(event: MouseEvent | PointerEvent): void {
+		const link = this.getLinkFromEvent(event);
+		if (!link) {
+			return;
+		}
 
-		if (link.hasAttribute(this.options.reloadAttribute)) return;
-		if (link.hasAttribute('download')) return;
+		const href = this.canInterceptLink(event, link);
+		if (!href) {
+			return;
+		}
 
-		const href = link.getAttribute('href');
-		if (!href) return;
+		this.pendingHoverNavigation = {
+			href,
+			timestamp: performance.now(),
+		};
 
-		if (href.startsWith('#')) return;
-		if (href.startsWith('javascript:')) return;
+		if (this.pendingNavigations > 0) {
+			this.queuedNavigationHref = href;
+		}
+	}
 
-		const url = new URL(href, window.location.origin);
+	private handleClick(event: MouseEvent): void {
+		const navigationRuntime = getEcoNavigationRuntime(window);
+		const link = this.getLinkFromEvent(event);
+		const href = link
+			? this.canInterceptLink(event, link)
+			: (this.getRecoveredPointerHref() ?? this.getRecoveredHoverHref());
+		this.pendingPointerNavigation = null;
+		this.pendingHoverNavigation = null;
+		if (!href) return;
+		this.queuedNavigationHref = null;
+
+		if (this.isAnotherNavigationRuntimeActive()) {
+			event.preventDefault();
+			event.stopImmediatePropagation();
+			void navigationRuntime.requestNavigation({
+				href,
+				direction: 'forward',
+				source: 'browser-router',
+			});
+			return;
+		}
 
-		if (!this.isSameOrigin(url)) return;
+		const url = new URL(href, window.location.origin);
 
 		event.preventDefault();
+		if (this.pendingNavigations > 0) {
+			this.queuedNavigationHref = href;
+			this.cancelNavigationTransaction();
+			return;
+		}
 		this.performNavigation(url, 'forward');
 	}
 
@@ -160,6 +474,8 @@ export class EcoRouter {
 	 * Triggered by the History API's popstate event.
 	 */
 	private handlePopState(_event: PopStateEvent): void {
+		if (this.isAnotherNavigationRuntimeActive()) return;
+
 		const url = new URL(window.location.href);
 		this.performNavigation(url, 'back');
 	}
@@ -172,6 +488,23 @@ export class EcoRouter {
 		return url.origin === window.location.origin;
 	}
 
+	private cancelNavigationTransaction(): void {
+		getEcoNavigationRuntime(window).cancelCurrentNavigationTransaction();
+	}
+
+	private beginNavigationTransaction(): {
+		isStaleNavigation: () => boolean;
+		signal: AbortSignal;
+		complete: () => void;
+	} {
+		const transaction = getEcoNavigationRuntime(window).beginNavigationTransaction();
+		return {
+			isStaleNavigation: () => !transaction.isCurrent(),
+			signal: transaction.signal,
+			complete: () => transaction.complete(),
+		};
+	}
+
 	/**
 	 * Executes the core navigation flow.
 	 *
@@ -191,79 +524,57 @@ export class EcoRouter {
 	 * @param direction - Navigation direction ('forward', 'back', or 'replace')
 	 */
 	private async performNavigation(url: URL, direction: EcoNavigationEvent['direction']): Promise<void> {
-		const previousUrl = new URL(window.location.href);
-
-		this.abortController?.abort();
-		this.abortController = new AbortController();
+		this.pendingNavigations++;
+		const { isStaleNavigation, signal, complete } = this.beginNavigationTransaction();
+		let queuedNavigationHref: string | null = null;
 
 		try {
-			const html = await this.fetchPage(url, this.abortController.signal);
-			const newDocument = this.domSwapper.parseHTML(html, url);
-
-			let shouldReload = false;
-			const beforeSwapEvent: EcoBeforeSwapEvent = {
-				url,
-				direction,
-				newDocument,
-				reload: () => {
-					shouldReload = true;
-				},
-			};
-
-			document.dispatchEvent(new CustomEvent('eco:before-swap', { detail: beforeSwapEvent }));
-
-			if (shouldReload) {
-				window.location.href = url.href;
-				return;
-			}
-
-			if (this.options.updateHistory && direction === 'forward') {
-				window.history.pushState({}, '', url.href);
-			} else if (direction === 'replace') {
-				window.history.replaceState({}, '', url.href);
-			}
-
-			const useViewTransitions = this.options.viewTransitions;
-			await this.domSwapper.preloadStylesheets(newDocument);
-
-			if (useViewTransitions) {
-				await this.viewTransitionManager.transition(() => {
-					this.domSwapper.morphHead(newDocument);
-					this.domSwapper.morphBody(newDocument);
-					this.scrollManager.handleScroll(url, previousUrl);
-				});
-			} else {
-				this.domSwapper.morphHead(newDocument);
-				this.domSwapper.replaceBody(newDocument);
-				this.scrollManager.handleScroll(url, previousUrl);
-			}
-
-			const afterSwapEvent: EcoAfterSwapEvent = {
-				url,
-				direction,
-			};
-
-			document.dispatchEvent(new CustomEvent('eco:after-swap', { detail: afterSwapEvent }));
+			const html = await this.fetchPage(url, signal);
+			if (isStaleNavigation()) return;
 
-			this.prefetchManager?.observeNewLinks();
-
-			// Cache the visited page for instant revisits (stale-while-revalidate)
-			this.prefetchManager?.cacheVisitedPage(url.href, html);
+			const newDocument = this.domSwapper.parseHTML(html, url);
+			if (isStaleNavigation()) return;
 
-			requestAnimationFrame(() => {
-				document.dispatchEvent(
-					new CustomEvent('eco:page-load', {
-						detail: { url, direction } as EcoNavigationEvent,
-					}),
-				);
+			await this.commitDocumentNavigation(url, direction, newDocument, {
+				html,
+				isStaleNavigation,
 			});
 		} catch (error) {
+			if (isStaleNavigation()) return;
+
 			if (error instanceof Error && error.name === 'AbortError') {
 				return;
 			}
 
 			console.error('[ecopages] Navigation failed:', error);
 			window.location.href = url.href;
+		} finally {
+			complete();
+			this.pendingNavigations--;
+
+			const navigationRuntime = getEcoNavigationRuntime(window);
+			if (!navigationRuntime.hasPendingNavigationTransaction()) {
+				queuedNavigationHref = this.queuedNavigationHref;
+				this.queuedNavigationHref = null;
+			}
+
+			if (queuedNavigationHref && queuedNavigationHref !== window.location.pathname + window.location.search) {
+				const ownerState = navigationRuntime.getOwnerState();
+
+				if (
+					ownerState.owner !== 'none' &&
+					ownerState.owner !== 'browser-router' &&
+					ownerState.canHandleSpaNavigation
+				) {
+					void navigationRuntime.requestNavigation({
+						href: queuedNavigationHref,
+						direction: 'forward',
+						source: 'browser-router',
+					});
+				} else {
+					void this.performNavigation(new URL(queuedNavigationHref, window.location.origin), 'forward');
+				}
+			}
 		}
 	}
 
@@ -296,13 +607,32 @@ export class EcoRouter {
 	}
 }
 
+const ACTIVE_ROUTER_KEY = '__ecopages_browser_router__';
+
+type RouterWindow = Window &
+	typeof globalThis & {
+		[ACTIVE_ROUTER_KEY]?: EcoRouter;
+	};
+
 /**
  * Creates and starts a router instance.
+ *
+ * Stops the previously active router (if any) before creating a new one so
+ * click listeners and coordinator registrations from earlier instances are
+ * cleaned up on re-execution (e.g. when the layout script is re-run via
+ * `data-eco-rerun` after a browser-router page commit).
+ *
  * @param options - Configuration options for the router
  * @returns A started EcoRouter instance
  */
 export function createRouter(options?: EcoRouterOptions): EcoRouter {
+	const win = window as RouterWindow;
+	const existingRouter = win[ACTIVE_ROUTER_KEY];
+	if (existingRouter) {
+		return existingRouter;
+	}
 	const router = new EcoRouter(options);
+	win[ACTIVE_ROUTER_KEY] = router;
 	router.start();
 	return router;
 }

package/src/client/services/dom-swapper.d.ts

@@ -12,6 +12,9 @@
  */
 export declare class DomSwapper {
     private persistAttribute;
+    private pendingHeadScripts;
+    private pendingRerunScripts;
+    private rerunNonce;
     constructor(persistAttribute: string);
     /**
      * Parses HTML string into a Document, injecting a temporary base tag for URL resolution.
@@ -38,12 +41,22 @@ export declare class DomSwapper {
      * - Injects new scripts from the incoming page that are absent from the current head
      */
     morphHead(newDocument: Document): void;
+    /**
+     * Replays queued `data-eco-rerun` scripts after the body swap completes.
+     *
+     * Scripts are intentionally flushed after the new body is in place so DOM-
+     * dependent bootstraps bind against the incoming page rather than the page
+     * being replaced.
+     */
+    flushRerunScripts(): void;
+    shouldReplaceBodyForRerunScripts(): boolean;
     /**
      * Detects custom elements without shadow DOM (light-DOM custom elements).
      * These need full replacement rather than morphing, because morphdom would
      * strip JS-generated content from their light DOM children.
      */
     private isLightDomCustomElement;
+    private replaceCustomElement;
     /**
      * Morphs document body using morphdom.
      * Preserves persisted elements and hydrated custom elements.
@@ -57,6 +70,16 @@ export declare class DomSwapper {
      * Use when View Transitions are disabled.
      */
     replaceBody(newDocument: Document): void;
+    private collectRerunScripts;
+    private removeStaleHeadScripts;
+    private shouldPersistExecutableInlineHeadScript;
+    private isNonExecutableHeadScript;
+    private areHeadScriptsEquivalent;
+    private getHeadScriptKey;
+    private findExistingHeadScript;
+    private findExistingRerunScript;
+    private isExternalModuleRerunScript;
+    private createRerunScriptUrl;
     /**
      * Manually attaches declarative shadow DOM templates.
      * Browsers only process `<template shadowrootmode>` during initial parse.