@ecopages/react-router 0.2.0-alpha.9 → 0.2.1

package/CHANGELOG.md

@@ -4,14 +4,12 @@ All notable changes to `@ecopages/react-router` are documented here.
 
 > **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
 
-## [UNRELEASED] — TBD
+## [0.2.1] — 2026-04-16
 
 ### Bug Fixes
 
-- Fixed React-to-non-React handoffs to replay queued clicks through the next active runtime and reuse prefetched HTML documents instead of forcing a second fetch.
-- Fixed stale handoff cleanup and fallback races so older React-router or browser-router navigations cannot overwrite a newer navigation.
-- Standardized React route payload reads on `window.__ECO_PAGES__.page` and explicit document owner markers so mixed-router page ownership stays stable.
-- Restored current-page HMR refreshes with persist layouts enabled by targeting the active React-router owner.
+- Fixed React-to-browser-router handoffs, queued-click replay, and stale-navigation races during mixed-router navigations.
+- Standardized route payload reads, document-owner markers, rerun scripts, and current-page HMR refreshes for persisted React layouts.
 
 ### Refactoring
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/react-router",
-  "version": "0.2.0-alpha.9",
+  "version": "0.2.1",
   "description": "Client-side SPA router for EcoPages React applications",
   "keywords": [
     "ecopages",
@@ -32,8 +32,8 @@
     "directory": "packages/react-router"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.9",
-    "@ecopages/react": "0.2.0-alpha.9"
+    "@ecopages/core": "0.2.1",
+    "@ecopages/react": "0.2.1"
   },
   "dependencies": {
     "react": "^19",

package/src/head-morpher.d.ts

@@ -3,6 +3,10 @@
  * Intelligently syncs head elements between pages using key-based diffing.
  * @module
  */
+export type HeadMorphResult = {
+    cleanup: () => void;
+    flushRerunScripts: () => void;
+};
 /**
  * Morphs the current document head to match the new document's head.
  * Now splits the process into adding new elements and returning a cleanup function
@@ -10,6 +14,6 @@
  * don't disappear before the "old" snapshot is taken.
  *
  * @param newDocument - The parsed document from the navigation target
- * @returns Promise that resolves to a cleanup function when new stylesheets have loaded
+ * @returns Promise that resolves to cleanup and rerun hooks when new stylesheets have loaded
  */
-export declare function morphHead(newDocument: Document): Promise<() => void>;
+export declare function morphHead(newDocument: Document): Promise<HeadMorphResult>;

package/src/head-morpher.js

@@ -1,4 +1,6 @@
 const PRESERVE_SELECTORS = ['script[type="importmap"]', "meta[charset]", "[data-eco-persist]"];
+const RERUN_SRC_ATTR = "data-eco-rerun-src";
+let rerunNonce = 0;
 function isNonExecutableHeadScript(el) {
   if (el.tagName !== "SCRIPT") {
     return false;
@@ -31,6 +33,13 @@ function shouldPersistExecutableInlineHeadScript(el) {
   }
   return !isNonExecutableHeadScript(el);
 }
+function isRerunScript(el) {
+  return el.tagName === "SCRIPT" && el.hasAttribute("data-eco-rerun");
+}
+function isHydrationScript(el) {
+  const src = el.getAttribute("src");
+  return !!src && src.includes("hydration.js") && src.includes("ecopages-react");
+}
 function getHeadElementKey(el) {
   const tag = el.tagName.toLowerCase();
   switch (tag) {
@@ -52,7 +61,7 @@ function getHeadElementKey(el) {
       if (el.getAttribute("type") === "importmap") return "importmap";
       const scriptId = el.getAttribute("data-eco-script-id") || el.getAttribute("id");
       if (scriptId) return `script-id:${scriptId}`;
-      const src = el.src;
+      const src = el.getAttribute(RERUN_SRC_ATTR) || el.src;
       return src ? `script:${src}` : null;
     }
     case "style": {
@@ -70,6 +79,12 @@ async function morphHead(newDocument) {
   const newElements = /* @__PURE__ */ new Map();
   const stylesheetPromises = [];
   const elementsToRemove = [];
+  const pendingRerunScripts = Array.from(newHead.querySelectorAll("script[data-eco-rerun]")).filter((script) => !isHydrationScript(script)).map((script) => ({
+    attributes: Array.from(script.attributes).map((attr) => [attr.name, attr.value]),
+    textContent: script.textContent ?? "",
+    scriptId: script.getAttribute("data-eco-script-id"),
+    src: script.getAttribute("src")
+  }));
   for (const el of Array.from(currentHead.children)) {
     const key = getHeadElementKey(el);
     if (key) currentElements.set(key, el);
@@ -80,9 +95,11 @@ async function morphHead(newDocument) {
   }
   for (const [key, newEl] of newElements) {
     const currentEl = currentElements.get(key);
+    if (isRerunScript(newEl)) {
+      continue;
+    }
     if (!currentEl) {
-      const src = newEl.getAttribute("src");
-      if (newEl.tagName === "SCRIPT" && src && src.includes("hydration.js") && src.includes("ecopages-react")) {
+      if (newEl.tagName === "SCRIPT" && isHydrationScript(newEl)) {
         continue;
       }
       const cloned = newEl.cloneNode(true);
@@ -104,7 +121,7 @@ async function morphHead(newDocument) {
   }
   for (const newEl of Array.from(newHead.children)) {
     const key = getHeadElementKey(newEl);
-    if (!key) {
+    if (!key && !isRerunScript(newEl)) {
       currentHead.appendChild(newEl.cloneNode(true));
     }
   }
@@ -119,12 +136,55 @@ async function morphHead(newDocument) {
       }
     }
   }
-  return () => {
-    for (const el of elementsToRemove) {
-      el.remove();
+  return {
+    cleanup: () => {
+      for (const el of elementsToRemove) {
+        el.remove();
+      }
+    },
+    flushRerunScripts: () => {
+      for (const script of pendingRerunScripts) {
+        const replacement = document.createElement("script");
+        const shouldBustModuleSrc = isExternalModuleRerunScript(script);
+        for (const [name, value] of script.attributes) {
+          if (name === "src" && shouldBustModuleSrc) {
+            replacement.setAttribute(RERUN_SRC_ATTR, value);
+            replacement.setAttribute("src", createRerunScriptUrl(value));
+            continue;
+          }
+          replacement.setAttribute(name, value);
+        }
+        replacement.textContent = script.textContent;
+        const existingScript = findExistingRerunScript(script);
+        if (existingScript) {
+          existingScript.replaceWith(replacement);
+          continue;
+        }
+        document.head.appendChild(replacement);
+      }
     }
   };
 }
+function findExistingRerunScript(script) {
+  const scripts = Array.from(document.head.querySelectorAll("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;
+}
+function isExternalModuleRerunScript(script) {
+  if (!script.src) {
+    return false;
+  }
+  return script.attributes.some(([name, value]) => name === "type" && value === "module");
+}
+function createRerunScriptUrl(src) {
+  const url = new URL(src, document.baseURI);
+  url.searchParams.set("__eco_rerun", String(++rerunNonce));
+  return url.toString();
+}
 export {
   morphHead
 };

package/src/router.js

@@ -217,7 +217,7 @@ const EcoRouter = ({ page, pageProps, options: userOptions, children }) => {
         if (result) {
           const { Component, props, doc, finalPath, moduleUrl } = result;
           const nextPage = { Component, props };
-          const cleanupHead = await morphHead(doc);
+          const { cleanup: cleanupHead, flushRerunScripts } = await morphHead(doc);
           if (isStale()) {
             cleanupHead();
             return;
@@ -257,6 +257,7 @@ const EcoRouter = ({ page, pageProps, options: userOptions, children }) => {
                   if (isStale()) {
                     return;
                   }
+                  flushRerunScripts();
                   cleanupHead();
                   applyViewTransitionNames();
                 } finally {
@@ -266,8 +267,21 @@ const EcoRouter = ({ page, pageProps, options: userOptions, children }) => {
             });
             await navigationCommitPromise;
           } else {
+            pendingRenderRef.current?.resolve();
+            const renderDfd = createDeferred();
+            pendingRenderRef.current = {
+              navigationId,
+              page: nextPage,
+              resolve: renderDfd.resolve
+            };
             commitPageData(moduleUrl, props);
             setCurrentPage(nextPage);
+            await renderDfd.promise;
+            if (isStale()) {
+              cleanupHead();
+              return;
+            }
+            flushRerunScripts();
             cleanupHead();
             applyViewTransitionNames();
           }

package/browser.ts

@@ -1,17 +0,0 @@
-/**
- * Browser entry point for @ecopages/react-router.
- * This file exports only the client-side components needed for hydration.
- * @module
- */
-
-export { EcoRouter, PageContent } from './src/router.ts';
-export type { EcoRouterProps } from './src/router.ts';
-
-export { useRouter } from './src/context.ts';
-export type { RouterContextValue } from './src/context.ts';
-export { EcoPropsScript } from './src/props-script.ts';
-export type { EcoPropsScriptProps } from './src/props-script.ts';
-
-export { morphHead } from './src/head-morpher.ts';
-
-export type { PageState } from './src/navigation.ts';

package/src/adapter.ts

@@ -1,48 +0,0 @@
-/**
- * Router adapter for React integration.
- * @module
- */
-
-import type { ReactRouterAdapter } from '@ecopages/react/router-adapter';
-import type { EcoRouterOptions } from './types.ts';
-
-/**
- * Creates a ReactRouterAdapter for EcoPages React Router.
- * Use this with the React plugin to enable SPA navigation.
- *
- * @param options - Router configuration options
- * @example
- * ```ts
- * import { reactPlugin } from '@ecopages/react';
- * import { ecoRouter } from '@ecopages/react-router';
- *
- * export default {
- *   integrations: [reactPlugin({ router: ecoRouter() })],
- * };
- * ```
- *
- * @example
- * ```ts
- * // Disable view transitions
- * reactPlugin({ router: ecoRouter({ viewTransitions: false }) })
- * ```
- */
-export function ecoRouter(options?: EcoRouterOptions): ReactRouterAdapter {
-	return {
-		name: 'eco-router',
-		bundle: {
-			importPath: '@ecopages/react-router/browser.ts',
-			outputName: 'react-router-esm',
-			externals: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
-		},
-		importMapKey: '@ecopages/react-router',
-		components: {
-			router: 'EcoRouter',
-			pageContent: 'PageContent',
-		},
-		getRouterProps(page: string, props: string): string {
-			const optionsStr = options ? `, options: ${JSON.stringify(options)}` : '';
-			return `{ page: ${page}, pageProps: ${props}${optionsStr} }`;
-		},
-	};
-}

package/src/context.ts

@@ -1,25 +0,0 @@
-/**
- * Router context and hook for accessing navigation state.
- * @module
- */
-
-import { createContext, useContext } from 'react';
-
-export type RouterContextValue = {
-	navigate: (url: string) => void;
-	isNavigating: boolean;
-};
-
-export const RouterContext = createContext<RouterContextValue | null>(null);
-
-/**
- * Hook to access the router's navigate function and navigation state.
- * Must be used within an EcoRouter.
- *
- * @throws Error if used outside of EcoRouter
- */
-export const useRouter = (): RouterContextValue => {
-	const context = useContext(RouterContext);
-	if (!context) throw new Error('useRouter must be used within EcoRouter');
-	return context;
-};

package/src/head-morpher.ts

@@ -1,214 +0,0 @@
-/**
- * Head morphing utilities for client-side navigation.
- * Intelligently syncs head elements between pages using key-based diffing.
- * @module
- */
-
-const PRESERVE_SELECTORS = ['script[type="importmap"]', 'meta[charset]', '[data-eco-persist]'];
-
-function isNonExecutableHeadScript(el: Element): boolean {
-	if (el.tagName !== 'SCRIPT') {
-		return false;
-	}
-
-	const type = (el.getAttribute('type') ?? '').trim().toLowerCase();
-	if (!type) {
-		return false;
-	}
-
-	return ![
-		'application/javascript',
-		'application/ecmascript',
-		'module',
-		'text/ecmascript',
-		'text/javascript',
-	].includes(type);
-}
-
-function shouldPersistExecutableInlineHeadScript(el: Element): boolean {
-	if (el.tagName !== 'SCRIPT') {
-		return false;
-	}
-
-	const scriptId = el.getAttribute('data-eco-script-id') || el.getAttribute('id');
-	if (!scriptId) {
-		return false;
-	}
-
-	if (el.hasAttribute('data-eco-rerun')) {
-		return false;
-	}
-
-	if ((el as HTMLScriptElement).src) {
-		return false;
-	}
-
-	return !isNonExecutableHeadScript(el);
-}
-
-/**
- * Computes a unique key for a head element to enable diffing.
- * Elements with the same key are considered the same across navigations.
- */
-function getHeadElementKey(el: Element): string | null {
-	const tag = el.tagName.toLowerCase();
-
-	switch (tag) {
-		case 'title':
-			return 'title';
-
-		case 'meta': {
-			const name = el.getAttribute('name') || el.getAttribute('property') || el.getAttribute('http-equiv');
-			return name ? `meta:${name}` : null;
-		}
-
-		case 'link': {
-			const rel = el.getAttribute('rel');
-			const href = el.getAttribute('href');
-			if (rel === 'stylesheet' && href) return `stylesheet:${href}`;
-			if (rel === 'icon' || rel === 'shortcut icon') return 'favicon';
-			if (rel === 'canonical') return 'canonical';
-			return href ? `link:${href}` : null;
-		}
-
-		case 'script': {
-			if (el.getAttribute('type') === 'importmap') return 'importmap';
-			const scriptId = el.getAttribute('data-eco-script-id') || el.getAttribute('id');
-			if (scriptId) return `script-id:${scriptId}`;
-			const src = (el as HTMLScriptElement).src;
-			return src ? `script:${src}` : null;
-		}
-
-		case 'style': {
-			const dataId = el.getAttribute('data-eco-style');
-			return dataId ? `style:${dataId}` : null;
-		}
-
-		default:
-			return null;
-	}
-}
-
-/**
- * Morphs the current document head to match the new document's head.
- * Now splits the process into adding new elements and returning a cleanup function
- * to remove old ones. This is crucial for View Transitions to ensure styles
- * don't disappear before the "old" snapshot is taken.
- *
- * @param newDocument - The parsed document from the navigation target
- * @returns Promise that resolves to a cleanup function when new stylesheets have loaded
- */
-export async function morphHead(newDocument: Document): Promise<() => void> {
-	const currentHead = document.head;
-	const newHead = newDocument.head;
-
-	const currentElements = new Map<string, Element>();
-	const newElements = new Map<string, Element>();
-	const stylesheetPromises: Promise<void>[] = [];
-	const elementsToRemove: Element[] = [];
-
-	/**
-	 * First, map existing head elements by their keys
-	 * to enable efficient diffing.
-	 */
-	for (const el of Array.from(currentHead.children)) {
-		const key = getHeadElementKey(el);
-		if (key) currentElements.set(key, el);
-	}
-
-	/**
-	 * Next, map new head elements by their keys.
-	 * This allows us to see which elements are new, updated, or removed.
-	 */
-	for (const el of Array.from(newHead.children)) {
-		const key = getHeadElementKey(el);
-		if (key) newElements.set(key, el);
-	}
-
-	/**
-	 * Now, iterate over new elements to add or update them in the current head.
-	 */
-	for (const [key, newEl] of newElements) {
-		const currentEl = currentElements.get(key);
-
-		if (!currentEl) {
-			const src = newEl.getAttribute('src');
-			/**
-			 * Skip hydration scripts during SPA navigation to prevent re-mounting
-			 *
-			 * In an SPA transition, the EcoRouter is already running and handling the page update.
-			 * The new page's HTML includes a hydration script (for initial load support), but
-			 * if we let it execute now, it would re-bootstrap the React app from scratch,
-			 * causing a full re-mount, state loss, and a visual flash.
-			 *
-			 * By blocking this script, we ensure the router maintains control and state.
-			 */
-			if (newEl.tagName === 'SCRIPT' && src && src.includes('hydration.js') && src.includes('ecopages-react')) {
-				continue;
-			}
-
-			const cloned = newEl.cloneNode(true) as Element;
-
-			/**
-			 * If the new element is a stylesheet, we need to wait for it to load
-			 * before considering the head morph complete. This prevents FOUC.
-			 */
-			if (cloned.tagName === 'LINK' && (cloned as HTMLLinkElement).rel === 'stylesheet') {
-				const loadPromise = new Promise<void>((resolve) => {
-					(cloned as HTMLLinkElement).onload = () => resolve();
-					(cloned as HTMLLinkElement).onerror = () => resolve();
-				});
-				stylesheetPromises.push(loadPromise);
-			}
-
-			currentHead.appendChild(cloned);
-		} else if (key === 'title' && currentEl.textContent !== newEl.textContent) {
-			currentEl.textContent = newEl.textContent;
-		} else if (isNonExecutableHeadScript(newEl) && currentEl.textContent !== newEl.textContent) {
-			currentEl.textContent = newEl.textContent;
-		} else if (key.startsWith('style:') && currentEl.textContent !== newEl.textContent) {
-			currentEl.textContent = newEl.textContent;
-		}
-	}
-
-	/**
-	 * Finally, handle any new elements without keys (e.g., inline scripts/styles)
-	 */
-	for (const newEl of Array.from(newHead.children)) {
-		const key = getHeadElementKey(newEl);
-		if (!key) {
-			currentHead.appendChild(newEl.cloneNode(true));
-		}
-	}
-
-	/**
-	 * Wait for all new stylesheets to load before proceeding.
-	 */
-	if (stylesheetPromises.length > 0) {
-		await Promise.all(stylesheetPromises);
-	}
-
-	/**
-	 * Identify and prepare to remove any old elements
-	 * that are no longer present in the new head.
-	 */
-	for (const [key, el] of currentElements) {
-		if (!newElements.has(key)) {
-			const shouldPreserve = PRESERVE_SELECTORS.some((sel) => el.matches(sel));
-			if (!shouldPreserve && !shouldPersistExecutableInlineHeadScript(el)) {
-				elementsToRemove.push(el);
-			}
-		}
-	}
-
-	/**
-	 * Return a cleanup function to remove old elements.
-	 * This allows the caller to control when the removal happens,
-	 * which is important for View Transitions.
-	 */
-	return () => {
-		for (const el of elementsToRemove) {
-			el.remove();
-		}
-	};
-}

package/src/index.ts

@@ -1,21 +0,0 @@
-/**
- * EcoPages React Router - SPA navigation for React with SSR support.
- * @module
- */
-
-export { EcoRouter, PageContent } from './router.ts';
-export type { EcoRouterProps } from './router.ts';
-
-export { EcoPropsScript } from './props-script.ts';
-export type { EcoPropsScriptProps } from './props-script.ts';
-
-export { useRouter } from './context.ts';
-export type { RouterContextValue } from './context.ts';
-
-export type { EcoRouterOptions } from './types.ts';
-
-export { morphHead } from './head-morpher.ts';
-
-export type { PageState } from './navigation.ts';
-
-export { ecoRouter } from './adapter.ts';

package/src/manage-scroll.ts

@@ -1,47 +0,0 @@
-/**
- * Manages scroll position during navigations
- * @module
- */
-
-import type { EcoRouterOptions } from './types.ts';
-
-/**
- * Service for handling scroll position during page transitions.
- * Handles window scroll behavior and hash navigation.
- */
-/**
- * Handle window scroll position based on scrollBehavior option.
- * Hash links always scroll to target regardless of option.
- */
-export function manageScroll(
-	newUrl: URL,
-	previousUrl: URL,
-	options: {
-		scrollBehavior: Required<EcoRouterOptions>['scrollBehavior'];
-		smoothScroll: boolean;
-	},
-): void {
-	const { scrollBehavior, smoothScroll } = options;
-
-	if (newUrl.hash) {
-		const target = document.getElementById(newUrl.hash.slice(1));
-		target?.scrollIntoView({ behavior: smoothScroll ? 'smooth' : 'instant' });
-		return;
-	}
-
-	const behavior = smoothScroll ? 'smooth' : 'instant';
-
-	switch (scrollBehavior) {
-		case 'preserve':
-			break;
-		case 'auto':
-			if (newUrl.pathname !== previousUrl.pathname) {
-				window.scrollTo({ top: 0, left: 0, behavior });
-			}
-			break;
-		case 'top':
-		default:
-			window.scrollTo({ top: 0, left: 0, behavior });
-			break;
-	}
-}