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

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

@@ -8,6 +8,24 @@ import morphdom from 'morphdom';
 
 const DEFAULT_PERSIST_ATTR = 'data-eco-persist';
 
+type PendingRerunScript = {
+	parent: 'head' | 'body';
+	attributes: Array<[string, string]>;
+	textContent: string;
+	src: string | null;
+	scriptId: string | null;
+};
+
+type PendingHeadScript = {
+	attributes: Array<[string, string]>;
+	textContent: string;
+	src: string | null;
+	scriptId: string | null;
+	replaceExisting: boolean;
+};
+
+const RERUN_SRC_ATTR = 'data-eco-rerun-src';
+
 /**
  * Checks if element has a persist attribute (custom or default).
  */
@@ -31,6 +49,9 @@ function isHydratedCustomElement(element: Element): boolean {
  */
 export class DomSwapper {
 	private persistAttribute: string;
+	private pendingHeadScripts: PendingHeadScript[] = [];
+	private pendingRerunScripts: PendingRerunScript[] = [];
+	private rerunNonce = 0;
 
 	constructor(persistAttribute: string) {
 		this.persistAttribute = persistAttribute;
@@ -114,6 +135,10 @@ export class DomSwapper {
 	 * - Injects new scripts from the incoming page that are absent from the current head
 	 */
 	morphHead(newDocument: Document): void {
+		this.pendingHeadScripts = [];
+		this.pendingRerunScripts = this.collectRerunScripts(newDocument);
+		this.removeStaleHeadScripts(newDocument);
+
 		/** Update the document title if it has changed. */
 		const newTitle = newDocument.head.querySelector('title');
 		if (newTitle && document.title !== newTitle.textContent) {
@@ -139,31 +164,6 @@ export class DomSwapper {
 			}
 		}
 
-		/**
-		 * 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.
 		 *
@@ -189,31 +189,120 @@ export class DomSwapper {
 			if (script.hasAttribute('data-eco-rerun')) continue;
 
 			const src = script.getAttribute('src');
+			const scriptId = script.getAttribute('data-eco-script-id') || script.getAttribute('id');
+			const existingScript = this.findExistingHeadScript(script);
+
+			if (scriptId && existingScript) {
+				if (!this.isNonExecutableHeadScript(script)) {
+					continue;
+				}
+
+				if (this.areHeadScriptsEquivalent(script, existingScript)) {
+					continue;
+				}
+
+				this.pendingHeadScripts.push({
+					attributes: Array.from(script.attributes).map((attr) => [attr.name, attr.value]),
+					textContent: script.textContent ?? '',
+					src,
+					scriptId,
+					replaceExisting: true,
+				});
+				continue;
+			}
 
 			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);
+				this.pendingHeadScripts.push({
+					attributes: Array.from(script.attributes).map((attr) => [attr.name, attr.value]),
+					textContent: script.textContent ?? '',
+					src,
+					scriptId,
+					replaceExisting: false,
+				});
 				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);
+				this.pendingHeadScripts.push({
+					attributes: Array.from(script.attributes).map((attr) => [attr.name, attr.value]),
+					textContent: script.textContent ?? '',
+					src: null,
+					scriptId,
+					replaceExisting: false,
+				});
 				existingInlineContents.add(content);
 			}
 		}
 	}
 
+	/**
+	 * 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 {
+		for (const script of this.pendingHeadScripts) {
+			const replacement = document.createElement('script');
+
+			for (const [name, value] of script.attributes) {
+				replacement.setAttribute(name, value);
+			}
+
+			replacement.textContent = script.textContent;
+
+			const existingScript = this.findExistingHeadScript(script);
+			if (script.replaceExisting && existingScript) {
+				existingScript.replaceWith(replacement);
+				continue;
+			}
+
+			document.head.appendChild(replacement);
+		}
+
+		this.pendingHeadScripts = [];
+
+		for (const script of this.pendingRerunScripts) {
+			const targetParent = script.parent === 'body' ? document.body : document.head;
+			const replacement = document.createElement('script');
+			const shouldBustModuleSrc = this.isExternalModuleRerunScript(script);
+
+			for (const [name, value] of script.attributes) {
+				if (name === 'data-eco-rerun') {
+					continue;
+				}
+
+				if (name === 'src' && shouldBustModuleSrc) {
+					replacement.setAttribute(RERUN_SRC_ATTR, value);
+					replacement.setAttribute('src', this.createRerunScriptUrl(value));
+					continue;
+				}
+
+				replacement.setAttribute(name, value);
+			}
+
+			replacement.textContent = script.textContent;
+
+			const existingScript = this.findExistingRerunScript(targetParent, script);
+
+			if (existingScript) {
+				existingScript.replaceWith(replacement);
+				continue;
+			}
+
+			targetParent.appendChild(replacement);
+		}
+
+		this.pendingRerunScripts = [];
+	}
+
+	shouldReplaceBodyForRerunScripts(): boolean {
+		return this.pendingRerunScripts.length > 0;
+	}
+
 	/**
 	 * Detects custom elements without shadow DOM (light-DOM custom elements).
 	 * These need full replacement rather than morphing, because morphdom would
@@ -223,6 +312,16 @@ export class DomSwapper {
 		return element.localName.includes('-') && element.shadowRoot === null;
 	}
 
+	private replaceCustomElement(fromEl: Element, toEl: Element): false {
+		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;
+	}
+
 	/**
 	 * Morphs document body using morphdom.
 	 * Preserves persisted elements and hydrated custom elements.
@@ -238,7 +337,7 @@ export class DomSwapper {
 					return false;
 				}
 				if (isHydratedCustomElement(fromEl)) {
-					return false;
+					return this.replaceCustomElement(fromEl, toEl);
 				}
 
 				/**
@@ -250,13 +349,7 @@ export class DomSwapper {
 				 * 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;
+					return this.replaceCustomElement(fromEl, toEl);
 				}
 
 				if (fromEl.isEqualNode(toEl)) {
@@ -301,6 +394,164 @@ export class DomSwapper {
 		this.processDeclarativeShadowDOM(document.body);
 	}
 
+	private collectRerunScripts(newDocument: Document): PendingRerunScript[] {
+		return Array.from(newDocument.querySelectorAll<HTMLScriptElement>('script[data-eco-rerun]')).map((script) => ({
+			parent: script.closest('body') ? 'body' : 'head',
+			attributes: Array.from(script.attributes).map((attr) => [attr.name, attr.value]),
+			textContent: script.textContent ?? '',
+			src: script.getAttribute('src'),
+			scriptId: script.getAttribute('data-eco-script-id'),
+		}));
+	}
+
+	private removeStaleHeadScripts(newDocument: Document): void {
+		const nextScriptKeys = new Set(
+			Array.from(newDocument.head.querySelectorAll<HTMLScriptElement>('script'))
+				.map((script) => this.getHeadScriptKey(script))
+				.filter((key): key is string => key !== null),
+		);
+
+		for (const script of Array.from(document.head.querySelectorAll<HTMLScriptElement>('script'))) {
+			const key = this.getHeadScriptKey(script);
+			if (!key || nextScriptKeys.has(key)) {
+				continue;
+			}
+
+			if (this.shouldPersistExecutableInlineHeadScript(script)) {
+				continue;
+			}
+
+			script.remove();
+		}
+	}
+
+	private shouldPersistExecutableInlineHeadScript(script: HTMLScriptElement): boolean {
+		const scriptId = script.getAttribute('data-eco-script-id') || script.getAttribute('id');
+		if (!scriptId) {
+			return false;
+		}
+
+		if (script.hasAttribute('data-eco-rerun')) {
+			return false;
+		}
+
+		if (script.getAttribute(RERUN_SRC_ATTR) || script.getAttribute('src')) {
+			return false;
+		}
+
+		return !this.isNonExecutableHeadScript(script);
+	}
+
+	private isNonExecutableHeadScript(script: HTMLScriptElement): boolean {
+		const type = (script.getAttribute('type') ?? '').trim().toLowerCase();
+
+		if (!type) {
+			return false;
+		}
+
+		return ![
+			'application/javascript',
+			'application/ecmascript',
+			'module',
+			'text/ecmascript',
+			'text/javascript',
+		].includes(type);
+	}
+
+	private areHeadScriptsEquivalent(nextScript: HTMLScriptElement, currentScript: HTMLScriptElement): boolean {
+		if (this.getHeadScriptKey(nextScript) !== this.getHeadScriptKey(currentScript)) {
+			return false;
+		}
+
+		if ((nextScript.textContent ?? '') !== (currentScript.textContent ?? '')) {
+			return false;
+		}
+
+		const nextAttributes = Array.from(nextScript.attributes).map((attribute) => [attribute.name, attribute.value]);
+		const currentAttributes = Array.from(currentScript.attributes).map((attribute) => [
+			attribute.name,
+			attribute.value,
+		]);
+
+		if (nextAttributes.length !== currentAttributes.length) {
+			return false;
+		}
+
+		return nextAttributes.every(
+			([name, value], index) => currentAttributes[index]?.[0] === name && currentAttributes[index]?.[1] === value,
+		);
+	}
+
+	private getHeadScriptKey(
+		script: HTMLScriptElement | Pick<PendingHeadScript | PendingRerunScript, 'scriptId' | 'src' | 'textContent'>,
+	): string | null {
+		const scriptId =
+			script instanceof HTMLScriptElement
+				? script.getAttribute('data-eco-script-id') || script.getAttribute('id')
+				: script.scriptId;
+		if (scriptId) {
+			return `id:${scriptId}`;
+		}
+
+		const src =
+			script instanceof HTMLScriptElement
+				? script.getAttribute(RERUN_SRC_ATTR) || script.getAttribute('src')
+				: script.src;
+		if (src) {
+			return `src:${src}`;
+		}
+
+		const textContent = (script.textContent ?? '').trim();
+		return textContent ? `inline:${textContent}` : null;
+	}
+
+	private findExistingHeadScript(
+		script: HTMLScriptElement | Pick<PendingHeadScript | PendingRerunScript, 'scriptId' | 'src' | 'textContent'>,
+	): HTMLScriptElement | null {
+		const scriptKey = this.getHeadScriptKey(script);
+		if (!scriptKey) {
+			return null;
+		}
+
+		return (
+			Array.from(document.head.querySelectorAll<HTMLScriptElement>('script')).find(
+				(candidate) => this.getHeadScriptKey(candidate) === scriptKey,
+			) ?? null
+		);
+	}
+
+	private findExistingRerunScript(root: HTMLElement, script: PendingRerunScript): HTMLScriptElement | null {
+		const scripts = Array.from(root.querySelectorAll<HTMLScriptElement>('script'));
+
+		if (script.scriptId) {
+			return (
+				scripts.find((candidate) => candidate.getAttribute('data-eco-script-id') === script.scriptId) ?? null
+			);
+		}
+
+		return (
+			scripts.find(
+				(candidate) =>
+					(candidate.getAttribute(RERUN_SRC_ATTR) ?? candidate.getAttribute('src')) === script.src &&
+					(candidate.textContent ?? '') === script.textContent,
+			) ?? null
+		);
+	}
+
+	private isExternalModuleRerunScript(script: PendingRerunScript): boolean {
+		if (!script.src) {
+			return false;
+		}
+
+		return script.attributes.some(([name, value]) => name === 'type' && value === 'module');
+	}
+
+	private createRerunScriptUrl(src: string): string {
+		const url = new URL(src, document.baseURI);
+		url.searchParams.set('__eco_rerun', String(++this.rerunNonce));
+		return url.toString();
+	}
+
 	/**
 	 * Manually attaches declarative shadow DOM templates.
 	 * Browsers only process `<template shadowrootmode>` during initial parse.

package/src/client/services/view-transition-manager.d.ts

@@ -16,8 +16,14 @@ export declare class ViewTransitionManager {
     /**
      * Execute a callback with view transition if available and enabled.
      * Falls back to direct execution if not supported.
+     *
+     * Navigation correctness depends on the DOM update callback completing, not on
+     * the browser finishing the visual transition animation. Awaiting
+     * `finished` here can leave router transactions artificially in-flight and
+     * block later navigations during rapid repeated clicks, so the router waits
+     * for `updateCallbackDone` and lets the animation finish in the background.
      * @param callback - The DOM update callback to execute
-     * @returns Promise that resolves when the transition completes
+     * @returns Promise that resolves when the DOM update has committed
      */
     transition(callback: () => void | Promise<void>): Promise<void>;
 }

package/src/client/services/view-transition-manager.js

@@ -13,8 +13,14 @@ class ViewTransitionManager {
   /**
    * Execute a callback with view transition if available and enabled.
    * Falls back to direct execution if not supported.
+   *
+   * Navigation correctness depends on the DOM update callback completing, not on
+   * the browser finishing the visual transition animation. Awaiting
+   * `finished` here can leave router transactions artificially in-flight and
+   * block later navigations during rapid repeated clicks, so the router waits
+   * for `updateCallbackDone` and lets the animation finish in the background.
    * @param callback - The DOM update callback to execute
-   * @returns Promise that resolves when the transition completes
+   * @returns Promise that resolves when the DOM update has committed
    */
   async transition(callback) {
     if (!this.enabled || !this.isSupported()) {
@@ -26,11 +32,10 @@ class ViewTransitionManager {
       await callback();
       applyViewTransitionNames();
     });
-    try {
-      await transition.finished;
-    } finally {
+    void transition.finished.finally(() => {
       clearViewTransitionNames();
-    }
+    });
+    await transition.updateCallbackDone;
   }
 }
 export {

package/src/client/services/view-transition-manager.ts

@@ -26,8 +26,14 @@ export class ViewTransitionManager {
 	/**
 	 * Execute a callback with view transition if available and enabled.
 	 * Falls back to direct execution if not supported.
+	 *
+	 * Navigation correctness depends on the DOM update callback completing, not on
+	 * the browser finishing the visual transition animation. Awaiting
+	 * `finished` here can leave router transactions artificially in-flight and
+	 * block later navigations during rapid repeated clicks, so the router waits
+	 * for `updateCallbackDone` and lets the animation finish in the background.
 	 * @param callback - The DOM update callback to execute
-	 * @returns Promise that resolves when the transition completes
+	 * @returns Promise that resolves when the DOM update has committed
 	 */
 	async transition(callback: () => void | Promise<void>): Promise<void> {
 		if (!this.enabled || !this.isSupported()) {
@@ -52,15 +58,15 @@ export class ViewTransitionManager {
 			applyViewTransitionNames();
 		});
 
-		try {
-			await transition.finished;
-		} finally {
+		void transition.finished.finally(() => {
 			/**
-			 * Cleanup view transition names and dynamic styles after transition completes.
-			 * This prevents style pollution.
+			 * Cleanup view transition names and dynamic styles after the browser's
+			 * animation lifecycle completes.
 			 */
 			clearViewTransitionNames();
-		}
+		});
+
+		await transition.updateCallbackDone;
 	}
 }
 

package/src/client/types.d.ts

@@ -67,6 +67,9 @@ export interface EcoRouterOptions {
      */
     prefetch?: PrefetchConfig | false;
 }
+export type BrowserRouterNavigateOptions = {
+    direction?: 'forward' | 'back' | 'replace';
+};
 /** Events emitted during the navigation lifecycle */
 export interface EcoNavigationEvent {
     url: URL;

package/src/client/types.ts

@@ -73,6 +73,10 @@ export interface EcoRouterOptions {
 	prefetch?: PrefetchConfig | false;
 }
 
+export type BrowserRouterNavigateOptions = {
+	direction?: 'forward' | 'back' | 'replace';
+};
+
 /** Events emitted during the navigation lifecycle */
 export interface EcoNavigationEvent {
 	url: URL;