@ecopages/browser-router 0.2.0-alpha.1

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

@@ -0,0 +1,325 @@
+/**
+ * DOM morphing service for client-side navigation.
+ * Uses Idiomorph for body morphing and Turbo-style surgical updates for head.
+ * @module dom-swapper
+ */
+
+import morphdom from 'morphdom';
+
+const DEFAULT_PERSIST_ATTR = 'data-eco-persist';
+
+/**
+ * Checks if element has a persist attribute (custom or default).
+ */
+function isPersisted(element: Element, persistAttribute: string): boolean {
+	return element.hasAttribute(persistAttribute) || element.hasAttribute(DEFAULT_PERSIST_ATTR);
+}
+
+/**
+ * Detects hydrated custom elements (with shadow DOM) that should skip morphing.
+ */
+function isHydratedCustomElement(element: Element): boolean {
+	return element.localName.includes('-') && element.shadowRoot !== null;
+}
+
+/**
+ * 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 class DomSwapper {
+	private persistAttribute: string;
+
+	constructor(persistAttribute: string) {
+		this.persistAttribute = persistAttribute;
+	}
+
+	/**
+	 * Parses HTML string into a Document, injecting a temporary base tag for URL resolution.
+	 */
+	parseHTML(html: string, url?: URL): Document {
+		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: Document): Promise<void> {
+		const existingHrefs = new Set(
+			Array.from(document.head.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]')).map((l) => l.href),
+		);
+
+		const newStylesheetLinks = Array.from(
+			newDocument.head.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]'),
+		).filter((link) => !existingHrefs.has(link.href));
+
+		if (newStylesheetLinks.length === 0) {
+			return;
+		}
+
+		const TIMEOUT = 5000;
+		const loadPromises = newStylesheetLinks.map((link) => {
+			return new Promise<void>((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: Document): void {
+		/** Update the document title if it has changed. */
+		const newTitle = newDocument.head.querySelector('title');
+		if (newTitle && document.title !== newTitle.textContent) {
+			document.title = newTitle.textContent || '';
+		}
+
+		/** Merge meta tags: update existing ones whose content changed, append new ones. */
+		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));
+			}
+		}
+
+		/**
+		 * Re-execute scripts that are explicitly marked with `data-eco-rerun`.
+		 * Deduplication is performed via `data-eco-script-id` to prevent double execution.
+		 */
+		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);
+			}
+		}
+
+		/**
+		 * Inject new scripts from the incoming page that are not already loaded.
+		 *
+		 * When the client-side router swaps pages, the new page may require scripts
+		 * (e.g. custom-element definitions) that were not present on the previous page.
+		 * Because the browser only executes a <script> element when it is first parsed
+		 * or dynamically appended to the DOM, a fresh element must be created for each
+		 * new script — cloneNode() alone is not sufficient to trigger execution.
+		 *
+		 * - External scripts are matched by their `src` attribute.
+		 * - Inline scripts are matched by trimmed text content to avoid re-running duplicates.
+		 */
+		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) {
+			/** Skip scripts already handled by the `data-eco-rerun` mechanism above. */
+			if (script.hasAttribute('data-eco-rerun')) continue;
+
+			const src = script.getAttribute('src');
+
+			if (src) {
+				if (existingScriptSrcs.has(src)) continue;
+				/** New external script — append a freshly created element so the browser fetches and executes it. */
+				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 {
+				/** Inline script — skip if identical content is already present to avoid re-running on every navigation. */
+				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.
+	 */
+	private isLightDomCustomElement(element: Element): boolean {
+		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: Document): void {
+		const persistAttr = this.persistAttribute;
+
+		morphdom(document.body, newDocument.body, {
+			onBeforeElUpdated: (fromEl, toEl) => {
+				if (isPersisted(fromEl, persistAttr)) {
+					return false;
+				}
+				if (isHydratedCustomElement(fromEl)) {
+					return false;
+				}
+
+				/**
+				 * Light-DOM custom elements (e.g. <radiant-code-tabs>) often
+				 * generate DOM in connectedCallback that doesn't exist in the
+				 * server-rendered HTML. Morphdom would diff those children away.
+				 * Instead, replace the element entirely so the browser fires
+				 * disconnectedCallback on the old instance and connectedCallback
+				 * on the fresh one.
+				 */
+				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: Document): void {
+		const persistAttr = this.persistAttribute;
+
+		const persistedElements = document.body.querySelectorAll(`[${persistAttr}], [${DEFAULT_PERSIST_ATTR}]`);
+		const persistedMap = new Map<string, Element>();
+
+		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.
+	 */
+	private processDeclarativeShadowDOM(root: Element | Document | ShadowRoot): void {
+		const templates = root.querySelectorAll<HTMLTemplateElement>('template[shadowrootmode], template[shadowroot]');
+
+		for (const template of templates) {
+			const mode = (template.getAttribute('shadowrootmode') ||
+				template.getAttribute('shadowroot')) as ShadowRootMode;
+			const parent = template.parentElement;
+
+			if (parent && !parent.shadowRoot) {
+				const shadowRoot = parent.attachShadow({ mode });
+				shadowRoot.appendChild(template.content);
+				template.remove();
+
+				this.processDeclarativeShadowDOM(shadowRoot);
+			}
+		}
+	}
+}

package/src/client/services/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Services for the EcoPages transitions package
+ * @module
+ */
+export { DomSwapper } from './dom-swapper.js';
+export { ScrollManager } from './scroll-manager.js';
+export { ViewTransitionManager } from './view-transition-manager.js';
+export { PrefetchManager } from './prefetch-manager.js';

package/src/client/services/index.js

@@ -0,0 +1,10 @@
+import { DomSwapper } from "./dom-swapper.js";
+import { ScrollManager } from "./scroll-manager.js";
+import { ViewTransitionManager } from "./view-transition-manager.js";
+import { PrefetchManager } from "./prefetch-manager.js";
+export {
+  DomSwapper,
+  PrefetchManager,
+  ScrollManager,
+  ViewTransitionManager
+};

package/src/client/services/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Services for the EcoPages transitions package
+ * @module
+ */
+
+export { DomSwapper } from './dom-swapper.ts';
+export { ScrollManager } from './scroll-manager.ts';
+export { ViewTransitionManager } from './view-transition-manager.ts';
+export { PrefetchManager } from './prefetch-manager.ts';

package/src/client/services/prefetch-manager.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Prefetch manager for client-side navigation.
+ * Uses a single IntersectionObserver and hover detection for optimal performance.
+ * @module prefetch-manager
+ */
+export type PrefetchStrategy = 'viewport' | 'hover' | 'intent';
+export interface PrefetchOptions {
+    strategy: PrefetchStrategy;
+    delay: number;
+    noPrefetchAttribute: string;
+    respectDataSaver: boolean;
+    linkSelector: string;
+}
+export declare class PrefetchManager {
+    private options;
+    private prefetched;
+    private htmlCache;
+    private observer;
+    private hoverTimeouts;
+    constructor(options: Partial<PrefetchOptions>);
+    /**
+     * Initializes prefetching based on the configured strategy.
+     *
+     * Sets up IntersectionObserver for viewport-based prefetching and/or
+     * hover/focus listeners for intent-based prefetching. Immediately begins
+     * observing existing links on the page.
+     */
+    start(): void;
+    /**
+     * Cleans up all prefetch-related observers and event listeners.
+     * Cancels any pending hover timeouts.
+     */
+    stop(): void;
+    /**
+     * Fetches and caches HTML content for a given URL.
+     *
+     * Skips cross-origin URLs or already-prefetched URLs. On success, both the
+     * HTML content is cached and any new stylesheets are preloaded to prevent
+     * FOUC during navigation.
+     *
+     * @param href - The URL to prefetch
+     */
+    prefetch(href: string): Promise<void>;
+    /**
+     * Retrieves cached HTML for a URL.
+     *
+     * Returns cached content without consuming it, enabling stale-while-revalidate:
+     * - Returns cached HTML immediately for instant navigation
+     * - Use cacheVisitedPage() after navigation to update cache in background
+     *
+     * @param href - The URL to look up
+     * @returns The cached HTML string, or null if not cached
+     */
+    getCachedHtml(href: string): string | null;
+    /**
+     * Caches HTML content for a visited page and triggers background revalidation.
+     *
+     * Implements stale-while-revalidate pattern:
+     * - Immediately caches the provided HTML for instant revisits
+     * - Fetches fresh content in background for next visit (unless it's the current page)
+     *
+     * @param href - The URL of the visited page
+     * @param html - The HTML content to cache initially
+     */
+    cacheVisitedPage(href: string, html: string): void;
+    /**
+     * Checks if a URL has already been prefetched.
+     * @param href - The URL to check
+     */
+    isPrefetched(href: string): boolean;
+    /**
+     * Determines if prefetching should be enabled based on network conditions.
+     *
+     * Respects the user's data saver settings and avoids prefetching on slow
+     * connections (2g or slower) when `respectDataSaver` is enabled.
+     */
+    private shouldPrefetch;
+    /**
+     * Creates an IntersectionObserver to prefetch links as they enter the viewport.
+     *
+     * Uses a 50px root margin to trigger prefetching slightly before elements
+     * become visible, improving perceived performance.
+     */
+    private setupIntersectionObserver;
+    /**
+     * Attaches delegated event listeners for hover and focus-based prefetching.
+     *
+     * Uses event delegation on the document for efficient handling without
+     * attaching listeners to individual links.
+     */
+    private setupHoverListeners;
+    private handleMouseOver;
+    private handleMouseOut;
+    private handleFocusIn;
+    private handleFocusOut;
+    /**
+     * Extracts a valid anchor element from a DOM event.
+     *
+     * Returns null for links that should not be prefetched (opt-outs, downloads,
+     * hash links, javascript: URLs).
+     */
+    private getLinkFromEvent;
+    /**
+     * Resolves the prefetch strategy for a link element.
+     *
+     * Checks for per-link overrides via `data-eco-prefetch` attribute,
+     * falling back to the global strategy.
+     */
+    private getLinkStrategy;
+    /**
+     * Resolves the prefetch delay for a link element.
+     *
+     * Checks for per-link overrides via `data-eco-prefetch-delay` attribute,
+     * falling back to the global delay.
+     */
+    private getLinkDelay;
+    /**
+     * Schedules a prefetch request during browser idle time.
+     *
+     * Uses `requestIdleCallback` when available for non-blocking execution.
+     * Eager prefetches execute immediately.
+     *
+     * @param href - The URL to prefetch
+     * @param eager - If true, prefetch immediately without waiting for idle
+     */
+    private scheduleIdlePrefetch;
+    /**
+     * Schedules a prefetch after a hover delay.
+     *
+     * The delay prevents prefetching when users briefly pass over links
+     * without intent to navigate.
+     *
+     * @param href - The URL to prefetch
+     * @param delay - Milliseconds to wait before prefetching
+     */
+    private scheduleHoverPrefetch;
+    /**
+     * Cancels a pending hover-initiated prefetch.
+     * @param href - The URL whose prefetch should be cancelled
+     */
+    private cancelHoverPrefetch;
+    /**
+     * Begins observing all existing links on the page.
+     *
+     * Called once during initialization. Eager links are prefetched immediately;
+     * viewport-strategy links are registered with the IntersectionObserver.
+     */
+    private observeExistingLinks;
+    /**
+     * Observes newly added links after DOM mutations.
+     *
+     * Should be called after client-side navigation or dynamic content updates
+     * to ensure new links are tracked for prefetching.
+     *
+     * @param root - The root element to search for links (defaults to document)
+     */
+    observeNewLinks(root?: Element | Document): void;
+    /**
+     * Prefetches stylesheets discovered in HTML content.
+     *
+     * Parses the HTML to find stylesheet links, then creates preload hints
+     * for stylesheets not already present in the current document. This ensures
+     * styles are cached before navigation to prevent FOUC.
+     *
+     * @param html - The raw HTML string to parse
+     * @param url - The base URL for resolving relative stylesheet paths
+     */
+    private prefetchStylesheets;
+}