@ecopages/browser-router 0.2.0-alpha.1

package/src/client/eco-router.ts

@@ -0,0 +1,290 @@
+/**
+ * Client-side router for Ecopages with morphdom-based DOM diffing.
+ * @module eco-router
+ */
+
+import type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './types.ts';
+import { DEFAULT_OPTIONS } from './types.ts';
+import { DomSwapper, ScrollManager, ViewTransitionManager, PrefetchManager } from './services/index.ts';
+
+/**
+ * Intercepts same-origin link clicks and performs client-side navigation
+ * using morphdom for efficient DOM diffing. Supports View Transitions API.
+ */
+export class EcoRouter {
+	private options: Required<EcoRouterOptions>;
+	private abortController: AbortController | null = null;
+
+	private domSwapper: DomSwapper;
+	private scrollManager: ScrollManager;
+	private viewTransitionManager: ViewTransitionManager;
+	private prefetchManager: PrefetchManager | null = null;
+
+	constructor(options: EcoRouterOptions = {}) {
+		this.options = { ...DEFAULT_OPTIONS, ...options };
+
+		this.domSwapper = new DomSwapper(this.options.persistAttribute);
+		this.scrollManager = new ScrollManager(this.options.scrollBehavior, this.options.smoothScroll);
+		this.viewTransitionManager = new ViewTransitionManager(this.options.viewTransitions);
+
+		if (this.options.prefetch !== false) {
+			this.prefetchManager = new PrefetchManager({
+				...this.options.prefetch,
+				linkSelector: this.options.linkSelector,
+			});
+		}
+
+		this.handleClick = this.handleClick.bind(this);
+		this.handlePopState = this.handlePopState.bind(this);
+	}
+
+	/**
+	 * Starts the router and begins intercepting navigation.
+	 *
+	 * Attaches click handlers for links and popstate handlers for browser
+	 * back/forward buttons. Also starts the prefetch manager if configured.
+	 */
+	public start(): void {
+		document.addEventListener('click', this.handleClick);
+		window.addEventListener('popstate', this.handlePopState);
+		this.prefetchManager?.start();
+
+		// Cache the initial page for instant back-navigation
+		const initialHtml = document.documentElement.outerHTML;
+		this.prefetchManager?.cacheVisitedPage(window.location.href, initialHtml);
+	}
+
+	/**
+	 * Stops the router and cleans up all event listeners.
+	 * After calling this, navigation will fall back to full page reloads.
+	 */
+	public stop(): void {
+		document.removeEventListener('click', this.handleClick);
+		window.removeEventListener('popstate', this.handlePopState);
+		this.prefetchManager?.stop();
+	}
+
+	/**
+	 * Programmatic navigation.
+	 * Falls back to full page reload for cross-origin URLs.
+	 * @param href - The URL to navigate to
+	 * @param options - Navigation options
+	 * @param options.replace - If true, replaces the current history entry instead of pushing
+	 */
+	public async navigate(href: string, options: { replace?: boolean } = {}): Promise<void> {
+		const url = new URL(href, window.location.origin);
+
+		if (!this.isSameOrigin(url)) {
+			window.location.href = href;
+			return;
+		}
+
+		await this.performNavigation(url, options.replace ? 'replace' : 'forward');
+	}
+
+	/**
+	 * Manually prefetch a URL.
+	 * @param href - The URL to prefetch
+	 */
+	public async prefetch(href: string): Promise<void> {
+		if (!this.prefetchManager) {
+			console.warn('[ecopages] Prefetching is disabled. Enable it in router options.');
+			return;
+		}
+		return this.prefetchManager.prefetch(href);
+	}
+
+	/**
+	 * Intercepts link clicks for client-side navigation.
+	 *
+	 * Filters out clicks with modifier keys (opens new tab), non-left clicks,
+	 * external links, download links, and links with the reload attribute.
+	 *
+	 * 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;
+
+		if (!link) return;
+
+		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+		if (event.button !== 0) return;
+
+		const target = link.getAttribute('target');
+		if (target && target !== '_self') return;
+
+		if (link.hasAttribute(this.options.reloadAttribute)) return;
+		if (link.hasAttribute('download')) return;
+
+		const href = link.getAttribute('href');
+		if (!href) return;
+
+		if (href.startsWith('#')) return;
+		if (href.startsWith('javascript:')) return;
+
+		const url = new URL(href, window.location.origin);
+
+		if (!this.isSameOrigin(url)) return;
+
+		event.preventDefault();
+		this.performNavigation(url, 'forward');
+	}
+
+	/**
+	 * Handles browser back/forward navigation.
+	 * Triggered by the History API's popstate event.
+	 */
+	private handlePopState(_event: PopStateEvent): void {
+		const url = new URL(window.location.href);
+		this.performNavigation(url, 'back');
+	}
+
+	/**
+	 * Checks if a URL shares the same origin as the current page.
+	 * Cross-origin navigation always falls back to full page reload.
+	 */
+	private isSameOrigin(url: URL): boolean {
+		return url.origin === window.location.origin;
+	}
+
+	/**
+	 * Executes the core navigation flow.
+	 *
+	 * Orchestrates fetching, DOM swapping, and lifecycle events:
+	 *
+	 * 1. **Fetch** - Retrieves HTML (from cache or network)
+	 * 2. **eco:before-swap** - Allows listeners to force a full reload
+	 * 3. **History update** - Updates URL before DOM swap so Web Components
+	 *    see the correct URL in their `connectedCallback`
+	 * 4. **Stylesheet preload** - Prevents FOUC by loading styles first
+	 * 5. **DOM swap** - Morphs head/body, optionally with View Transition
+	 * 6. **Lifecycle events** - Dispatches `eco:after-swap` and `eco:page-load`
+	 *
+	 * Falls back to full page reload on network errors.
+	 *
+	 * @param url - The target URL to navigate to
+	 * @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();
+
+		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 }));
+
+			this.prefetchManager?.observeNewLinks();
+
+			// Cache the visited page for instant revisits (stale-while-revalidate)
+			this.prefetchManager?.cacheVisitedPage(url.href, html);
+
+			requestAnimationFrame(() => {
+				document.dispatchEvent(
+					new CustomEvent('eco:page-load', {
+						detail: { url, direction } as EcoNavigationEvent,
+					}),
+				);
+			});
+		} catch (error) {
+			if (error instanceof Error && error.name === 'AbortError') {
+				return;
+			}
+
+			console.error('[ecopages] Navigation failed:', error);
+			window.location.href = url.href;
+		}
+	}
+
+	/**
+	 * Fetches the HTML content of a page.
+	 * @param url - The URL to fetch
+	 * @param signal - AbortSignal for cancelling the request
+	 * @throws Error if the response is not ok
+	 */
+	private async fetchPage(url: URL, signal: AbortSignal): Promise<string> {
+		if (this.prefetchManager) {
+			const cachedHtml = this.prefetchManager.getCachedHtml(url.href);
+			if (cachedHtml) {
+				return cachedHtml;
+			}
+		}
+
+		const response = await fetch(url.href, {
+			signal,
+			headers: {
+				Accept: 'text/html',
+			},
+		});
+
+		if (!response.ok) {
+			throw new Error(`Failed to fetch page: ${response.status}`);
+		}
+
+		return response.text();
+	}
+}
+
+/**
+ * Creates and starts a router instance.
+ * @param options - Configuration options for the router
+ * @returns A started EcoRouter instance
+ */
+export function createRouter(options?: EcoRouterOptions): EcoRouter {
+	const router = new EcoRouter(options);
+	router.start();
+	return router;
+}
+
+export type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './types';

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

@@ -0,0 +1,65 @@
+/**
+ * DOM morphing service for client-side navigation.
+ * Uses Idiomorph for body morphing and Turbo-style surgical updates for head.
+ * @module dom-swapper
+ */
+/**
+ * Handles DOM manipulation during client-side page transitions.
+ *
+ * Uses a hybrid approach inspired by Turbo:
+ * - Surgical head updates (no morphing) to prevent FOUC
+ * - Idiomorph for efficient body diffing
+ */
+export declare class DomSwapper {
+    private persistAttribute;
+    constructor(persistAttribute: string);
+    /**
+     * Parses HTML string into a Document, injecting a temporary base tag for URL resolution.
+     */
+    parseHTML(html: string, url?: URL): Document;
+    /**
+     * Preloads new stylesheets from target document to prevent FOUC.
+     *
+     * Discovers stylesheet links in the target document that aren't present in the
+     * current document, creates corresponding link elements, and waits for all to
+     * load before resolving. This follows Turbo's approach of waiting for stylesheets
+     * before any DOM updates.
+     */
+    preloadStylesheets(newDocument: Document): Promise<void>;
+    /**
+     * Updates document head using Turbo-style surgical updates.
+     *
+     * This approach avoids morphing the head element entirely, which prevents
+     * browser repaints that cause FOUC. Instead, it:
+     * - Updates the document title
+     * - Merges meta tags (adds new, updates changed)
+     * - Leaves stylesheets untouched (they're preloaded separately)
+     * - Handles script re-execution for marked scripts
+     * - Injects new scripts from the incoming page that are absent from the current head
+     */
+    morphHead(newDocument: Document): void;
+    /**
+     * 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;
+    /**
+     * Morphs document body using morphdom.
+     * Preserves persisted elements and hydrated custom elements.
+     * Light-DOM custom elements are fully replaced to trigger proper
+     * disconnectedCallback → connectedCallback lifecycle.
+     */
+    morphBody(newDocument: Document): void;
+    /**
+     * Replaces body content in a single operation.
+     * Preserves persisted elements by moving them to the new body.
+     * Use when View Transitions are disabled.
+     */
+    replaceBody(newDocument: Document): void;
+    /**
+     * Manually attaches declarative shadow DOM templates.
+     * Browsers only process `<template shadowrootmode>` during initial parse.
+     */
+    private processDeclarativeShadowDOM;
+}

package/src/client/services/dom-swapper.js

@@ -0,0 +1,237 @@
+import morphdom from "morphdom";
+const DEFAULT_PERSIST_ATTR = "data-eco-persist";
+function isPersisted(element, persistAttribute) {
+  return element.hasAttribute(persistAttribute) || element.hasAttribute(DEFAULT_PERSIST_ATTR);
+}
+function isHydratedCustomElement(element) {
+  return element.localName.includes("-") && element.shadowRoot !== null;
+}
+class DomSwapper {
+  persistAttribute;
+  constructor(persistAttribute) {
+    this.persistAttribute = persistAttribute;
+  }
+  /**
+   * Parses HTML string into a Document, injecting a temporary base tag for URL resolution.
+   */
+  parseHTML(html, url) {
+    const parser = new DOMParser();
+    const htmlToParse = url ? `<base href="${url.href}" data-eco-injected>${html}` : html;
+    return parser.parseFromString(htmlToParse, "text/html");
+  }
+  /**
+   * Preloads new stylesheets from target document to prevent FOUC.
+   *
+   * Discovers stylesheet links in the target document that aren't present in the
+   * current document, creates corresponding link elements, and waits for all to
+   * load before resolving. This follows Turbo's approach of waiting for stylesheets
+   * before any DOM updates.
+   */
+  async preloadStylesheets(newDocument) {
+    const existingHrefs = new Set(
+      Array.from(document.head.querySelectorAll('link[rel="stylesheet"]')).map((l) => l.href)
+    );
+    const newStylesheetLinks = Array.from(
+      newDocument.head.querySelectorAll('link[rel="stylesheet"]')
+    ).filter((link) => !existingHrefs.has(link.href));
+    if (newStylesheetLinks.length === 0) {
+      return;
+    }
+    const TIMEOUT = 5e3;
+    const loadPromises = newStylesheetLinks.map((link) => {
+      return new Promise((resolve) => {
+        const newLink = document.createElement("link");
+        newLink.rel = "stylesheet";
+        newLink.media = link.media || "all";
+        const timeoutId = setTimeout(() => {
+          cleanup();
+          resolve();
+        }, TIMEOUT);
+        const cleanup = () => {
+          clearTimeout(timeoutId);
+          newLink.onload = null;
+          newLink.onerror = null;
+        };
+        newLink.onload = () => {
+          cleanup();
+          resolve();
+        };
+        newLink.onerror = () => {
+          cleanup();
+          resolve();
+        };
+        newLink.href = link.href;
+        document.head.appendChild(newLink);
+      });
+    });
+    await Promise.all(loadPromises);
+  }
+  /**
+   * Updates document head using Turbo-style surgical updates.
+   *
+   * This approach avoids morphing the head element entirely, which prevents
+   * browser repaints that cause FOUC. Instead, it:
+   * - Updates the document title
+   * - Merges meta tags (adds new, updates changed)
+   * - Leaves stylesheets untouched (they're preloaded separately)
+   * - Handles script re-execution for marked scripts
+   * - Injects new scripts from the incoming page that are absent from the current head
+   */
+  morphHead(newDocument) {
+    const newTitle = newDocument.head.querySelector("title");
+    if (newTitle && document.title !== newTitle.textContent) {
+      document.title = newTitle.textContent || "";
+    }
+    const newMetas = newDocument.head.querySelectorAll("meta[name], meta[property]");
+    for (const newMeta of newMetas) {
+      const name = newMeta.getAttribute("name");
+      const property = newMeta.getAttribute("property");
+      const content = newMeta.getAttribute("content");
+      const selector = name ? `meta[name="${name}"]` : `meta[property="${property}"]`;
+      const existingMeta = document.head.querySelector(selector);
+      if (existingMeta) {
+        if (existingMeta.getAttribute("content") !== content) {
+          existingMeta.setAttribute("content", content || "");
+        }
+      } else {
+        document.head.appendChild(newMeta.cloneNode(true));
+      }
+    }
+    const existingScriptIds = new Set(
+      Array.from(document.head.querySelectorAll("script[data-eco-script-id]")).map(
+        (s) => s.getAttribute("data-eco-script-id")
+      )
+    );
+    const rerunScripts = newDocument.head.querySelectorAll("script[data-eco-rerun]");
+    for (const script of rerunScripts) {
+      const scriptId = script.getAttribute("data-eco-script-id");
+      if (scriptId && !existingScriptIds.has(scriptId)) {
+        const newScript = document.createElement("script");
+        for (const attr of script.attributes) {
+          if (attr.name !== "data-eco-rerun") {
+            newScript.setAttribute(attr.name, attr.value);
+          }
+        }
+        newScript.textContent = script.textContent;
+        document.head.appendChild(newScript);
+      }
+    }
+    const existingScriptSrcs = new Set(
+      Array.from(document.head.querySelectorAll("script[src]")).map((s) => s.getAttribute("src"))
+    );
+    const existingInlineContents = new Set(
+      Array.from(document.head.querySelectorAll("script:not([src])")).map((s) => (s.textContent ?? "").trim())
+    );
+    const allNewHeadScripts = newDocument.head.querySelectorAll("script");
+    for (const script of allNewHeadScripts) {
+      if (script.hasAttribute("data-eco-rerun")) continue;
+      const src = script.getAttribute("src");
+      if (src) {
+        if (existingScriptSrcs.has(src)) continue;
+        const newScript = document.createElement("script");
+        for (const attr of script.attributes) {
+          newScript.setAttribute(attr.name, attr.value);
+        }
+        document.head.appendChild(newScript);
+        existingScriptSrcs.add(src);
+      } else {
+        const content = (script.textContent ?? "").trim();
+        if (!content || existingInlineContents.has(content)) continue;
+        const newScript = document.createElement("script");
+        for (const attr of script.attributes) {
+          newScript.setAttribute(attr.name, attr.value);
+        }
+        newScript.textContent = script.textContent;
+        document.head.appendChild(newScript);
+        existingInlineContents.add(content);
+      }
+    }
+  }
+  /**
+   * 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.
+   */
+  isLightDomCustomElement(element) {
+    return element.localName.includes("-") && element.shadowRoot === null;
+  }
+  /**
+   * Morphs document body using morphdom.
+   * Preserves persisted elements and hydrated custom elements.
+   * Light-DOM custom elements are fully replaced to trigger proper
+   * disconnectedCallback → connectedCallback lifecycle.
+   */
+  morphBody(newDocument) {
+    const persistAttr = this.persistAttribute;
+    morphdom(document.body, newDocument.body, {
+      onBeforeElUpdated: (fromEl, toEl) => {
+        if (isPersisted(fromEl, persistAttr)) {
+          return false;
+        }
+        if (isHydratedCustomElement(fromEl)) {
+          return false;
+        }
+        if (this.isLightDomCustomElement(fromEl)) {
+          const newEl = document.createElement(toEl.tagName);
+          for (const attr of toEl.attributes) {
+            newEl.setAttribute(attr.name, attr.value);
+          }
+          newEl.innerHTML = toEl.innerHTML;
+          fromEl.replaceWith(newEl);
+          return false;
+        }
+        if (fromEl.isEqualNode(toEl)) {
+          return false;
+        }
+        return true;
+      }
+    });
+    this.processDeclarativeShadowDOM(document.body);
+  }
+  /**
+   * Replaces body content in a single operation.
+   * Preserves persisted elements by moving them to the new body.
+   * Use when View Transitions are disabled.
+   */
+  replaceBody(newDocument) {
+    const persistAttr = this.persistAttribute;
+    const persistedElements = document.body.querySelectorAll(`[${persistAttr}], [${DEFAULT_PERSIST_ATTR}]`);
+    const persistedMap = /* @__PURE__ */ new Map();
+    for (const el of persistedElements) {
+      const key = el.getAttribute(persistAttr) || el.getAttribute(DEFAULT_PERSIST_ATTR);
+      if (key) {
+        persistedMap.set(key, el);
+      }
+    }
+    for (const [key, oldEl] of persistedMap) {
+      const placeholder = newDocument.body.querySelector(
+        `[${persistAttr}="${key}"], [${DEFAULT_PERSIST_ATTR}="${key}"]`
+      );
+      if (placeholder) {
+        placeholder.replaceWith(oldEl);
+      }
+    }
+    document.body.replaceChildren(...newDocument.body.childNodes);
+    this.processDeclarativeShadowDOM(document.body);
+  }
+  /**
+   * Manually attaches declarative shadow DOM templates.
+   * Browsers only process `<template shadowrootmode>` during initial parse.
+   */
+  processDeclarativeShadowDOM(root) {
+    const templates = root.querySelectorAll("template[shadowrootmode], template[shadowroot]");
+    for (const template of templates) {
+      const mode = template.getAttribute("shadowrootmode") || template.getAttribute("shadowroot");
+      const parent = template.parentElement;
+      if (parent && !parent.shadowRoot) {
+        const shadowRoot = parent.attachShadow({ mode });
+        shadowRoot.appendChild(template.content);
+        template.remove();
+        this.processDeclarativeShadowDOM(shadowRoot);
+      }
+    }
+  }
+}
+export {
+  DomSwapper
+};