@ecopages/react-router 0.2.0-alpha.9 → 0.2.0-beta.1

package/README.md

@@ -23,7 +23,7 @@ This keeps React-router focused on React rendering while still allowing mixed Re
 ## Installation
 
 ```bash
-bunx jsr add @ecopages/react-router
+bun add @ecopages/react-router
 ```
 
 ## Quick Start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/react-router",
-  "version": "0.2.0-alpha.9",
+  "version": "0.2.0-beta.1",
   "description": "Client-side SPA router for EcoPages React applications",
   "keywords": [
     "ecopages",
@@ -32,12 +32,12 @@
     "directory": "packages/react-router"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.9",
-    "@ecopages/react": "0.2.0-alpha.9"
+    "@ecopages/core": "0.2.0-beta.1",
+    "@ecopages/react": "0.2.0-beta.1"
   },
   "dependencies": {
-    "react": "^19",
-    "react-dom": "^19.2.4"
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
   },
   "types": "./src/index.d.ts"
 }

package/src/adapter.js

@@ -2,11 +2,10 @@ function ecoRouter(options) {
   return {
     name: "eco-router",
     bundle: {
-      importPath: "@ecopages/react-router/browser.ts",
+      importPath: "@ecopages/react-router/browser",
       outputName: "react-router-esm",
       externals: ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime"]
     },
-    importMapKey: "@ecopages/react-router",
     components: {
       router: "EcoRouter",
       pageContent: "PageContent"

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,7 @@
-const PRESERVE_SELECTORS = ['script[type="importmap"]', "meta[charset]", "[data-eco-persist]"];
+import { isReactRouterPageBootstrapAssetSrc } from "./hydration-assets.js";
+const PRESERVE_SELECTORS = ["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 +34,17 @@ function shouldPersistExecutableInlineHeadScript(el) {
   }
   return !isNonExecutableHeadScript(el);
 }
+function isRerunScript(el) {
+  return el.tagName === "SCRIPT" && el.hasAttribute("data-eco-rerun");
+}
+function isReactRouterPageBootstrapScriptId(scriptId) {
+  return !!scriptId && scriptId.startsWith("ecopages-react-") && !scriptId.startsWith("ecopages-react-island-");
+}
+function isHydrationScript(el) {
+  const src = el.getAttribute("src");
+  const scriptId = el.getAttribute("data-eco-script-id");
+  return isReactRouterPageBootstrapScriptId(scriptId) || !!src && isReactRouterPageBootstrapAssetSrc(src);
+}
 function getHeadElementKey(el) {
   const tag = el.tagName.toLowerCase();
   switch (tag) {
@@ -49,10 +63,9 @@ function getHeadElementKey(el) {
       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.src;
+      const src = el.getAttribute(RERUN_SRC_ATTR) || el.src;
       return src ? `script:${src}` : null;
     }
     case "style": {
@@ -70,6 +83,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 +99,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 +125,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 +140,70 @@ 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 registeredRerun = getRegisteredRerunScript(script.scriptId);
+        const replacement = document.createElement("script");
+        const shouldBustModuleSrc = isExternalModuleRerunScript(script) && !registeredRerun;
+        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 (registeredRerun) {
+          if (!existingScript) {
+            document.head.appendChild(replacement);
+          }
+          registeredRerun();
+          continue;
+        }
+        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 getRegisteredRerunScript(scriptId) {
+  if (!scriptId) {
+    return null;
+  }
+  const runtimeWindow = window;
+  return runtimeWindow.__ECO_PAGES__?.rerunScripts?.[scriptId] ?? null;
+}
+function createRerunScriptUrl(src) {
+  const url = new URL(src, document.baseURI);
+  url.searchParams.set("__eco_rerun", String(++rerunNonce));
+  return url.toString();
+}
 export {
   morphHead
 };

package/src/hydration-assets.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns whether a script URL belongs to a router-managed React page bootstrap asset.
+ */
+export declare function isReactRouterPageBootstrapAssetSrc(src: string): boolean;
+/**
+ * Returns whether a script URL follows the legacy React hydration asset naming pattern.
+ */
+export declare function isReactHydrationAssetSrc(src: string): boolean;
+/**
+ * Returns whether a script URL should be treated as the page module source during router navigation.
+ */
+export declare function isReactPageHydrationAssetSrc(src: string): boolean;

package/src/hydration-assets.js

@@ -0,0 +1,17 @@
+function isReactPageAssetName(src) {
+  return src.includes("ecopages-react-") && src.endsWith(".js");
+}
+function isReactRouterPageBootstrapAssetSrc(src) {
+  return isReactPageAssetName(src) && !src.includes("ecopages-react-island-");
+}
+function isReactHydrationAssetSrc(src) {
+  return isReactPageAssetName(src) && src.includes("hydration.js");
+}
+function isReactPageHydrationAssetSrc(src) {
+  return isReactRouterPageBootstrapAssetSrc(src);
+}
+export {
+  isReactHydrationAssetSrc,
+  isReactPageHydrationAssetSrc,
+  isReactRouterPageBootstrapAssetSrc
+};

package/src/navigation.d.ts

@@ -23,12 +23,23 @@ export type FetchedPageDocument = {
 type LoadPageModuleOptions = {
     signal?: AbortSignal;
 };
+type LoadPageModuleFromDocumentOptions = {
+    /**
+     * Explicit page module URL to import instead of extracting one from the
+     * document's hydration assets.
+     *
+     * React Router uses this during HMR-driven reloads so the active hot module
+     * entry wins over any static bootstrap asset references embedded in the HTML.
+     */
+    moduleUrlOverride?: string;
+};
 export type InterceptDecision = {
     shouldIntercept: true;
 } | {
     shouldIntercept: false;
-    reason: 'modified-click' | 'non-left-click' | 'external-target' | 'explicit-reload' | 'download' | 'invalid-href' | 'cross-origin';
+    reason: 'modified-click' | 'non-left-click' | 'external-target' | 'explicit-reload' | 'download' | 'invalid-href' | 'cross-origin' | 'same-page-hash';
 };
+export declare function isSamePageHashNavigationHref(href: string): boolean;
 /**
  * Determines whether a link click should be intercepted for client-side navigation.
  *
@@ -69,7 +80,21 @@ export declare function extractComponentUrl(doc: Document): Promise<string | nul
  */
 export declare function loadPageModule(url: string, options?: LoadPageModuleOptions): Promise<LoadedPageModule | null>;
 export declare function fetchPageDocument(url: string, options?: LoadPageModuleOptions): Promise<FetchedPageDocument | null>;
-export declare function loadPageModuleFromDocument(doc: Document, finalPath: string): Promise<LoadedPageModule | null>;
+/**
+ * Loads the page module for a fetched or current document.
+ *
+ * The router normally extracts the page module URL from the document's
+ * hydration assets. Callers can provide `options.moduleUrlOverride` when the
+ * document is stale with respect to the active runtime module identity, such as
+ * during HMR-driven current-page reloads.
+ *
+ * @param doc - Parsed destination document.
+ * @param finalPath - Final route path after redirects.
+ * @param options - Module loading overrides.
+ * @returns Loaded page module payload or `null` when the document is not a
+ * React-router page or no page component can be resolved.
+ */
+export declare function loadPageModuleFromDocument(doc: Document, finalPath: string, options?: LoadPageModuleFromDocumentOptions): Promise<LoadedPageModule | null>;
 /**
  * Convenience wrapper around getInterceptDecision that returns a boolean.
  * Use getInterceptDecision directly when you need the reason for debugging.

package/src/navigation.js

@@ -1,7 +1,13 @@
 import { getEcoDocumentOwner } from "@ecopages/core/router/navigation-coordinator";
+import { isReactPageHydrationAssetSrc } from "./hydration-assets.js";
 const ROUTER_PROPS_SCRIPT_ID = "__ECO_PAGE_DATA__";
-function isReactPageHydrationAsset(src) {
-  return src.includes("ecopages-react-") && src.includes("hydration.js") && !src.includes("ecopages-react-island-");
+function isSamePageHashNavigationHref(href) {
+  if (!href) {
+    return false;
+  }
+  const currentUrl = new URL(window.location.href);
+  const targetUrl = new URL(href, currentUrl);
+  return targetUrl.origin === currentUrl.origin && targetUrl.hash.length > 0 && targetUrl.pathname === currentUrl.pathname && targetUrl.search === currentUrl.search;
 }
 function getInterceptDecision(event, link, options) {
   if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
@@ -18,6 +24,9 @@ function getInterceptDecision(event, link, options) {
   }
   const url = new URL(href, window.location.origin);
   if (url.origin !== window.location.origin) return { shouldIntercept: false, reason: "cross-origin" };
+  if (isSamePageHashNavigationHref(href)) {
+    return { shouldIntercept: false, reason: "same-page-hash" };
+  }
   return { shouldIntercept: true };
 }
 function extractComponentUrlFromMarker(doc) {
@@ -28,7 +37,30 @@ function extractComponentUrlFromMarker(doc) {
 }
 const DEFAULT_IMPORT_REGEX = /import\s+(\w+)\s+from\s*['"]([^'"]+)['"]/;
 const NAMESPACE_IMPORT_REGEX = /import\s*\*\s*as\s*(\w+)\s*from\s*['"]([^'"]+)['"]/;
-function extractModulePathFromCode(code) {
+const PAGE_MODULE_MARKER_REGEX = /__ECO_PAGES__\.page\s*=\s*\{\s*module\s*:\s*['"]([^'"]+)['"]/;
+const PAGE_MODULE_IDENTIFIER_REGEX = /__ECO_PAGES__\.page\s*=\s*\{\s*module\s*:\s*([A-Za-z_$][\w$]*)\s*,/;
+const PAGE_BOOTSTRAP_SELECTOR = 'script[data-eco-page-bootstrap="react-router"]';
+function extractModulePathFromCode(code, fallbackUrl) {
+  const markerMatch = code.match(PAGE_MODULE_MARKER_REGEX);
+  if (markerMatch) {
+    return markerMatch[1] ?? null;
+  }
+  const moduleIdentifier = code.match(PAGE_MODULE_IDENTIFIER_REGEX)?.[1];
+  if (moduleIdentifier) {
+    const assignmentRegex = new RegExp(
+      `(?:const|let|var)[^;]*\\b${moduleIdentifier}\\s*=\\s*(?:['"]([^'"]+)['"]|(import\\.meta\\.url))`
+    );
+    const assignmentMatch = code.match(assignmentRegex);
+    if (assignmentMatch?.[1]) {
+      return assignmentMatch[1];
+    }
+    if (fallbackUrl && assignmentMatch?.[2]) {
+      return fallbackUrl;
+    }
+  }
+  if (fallbackUrl && code.includes("module:import.meta.url")) {
+    return fallbackUrl;
+  }
   const defaultMatch = code.match(DEFAULT_IMPORT_REGEX);
   const namespaceMatch = code.match(NAMESPACE_IMPORT_REGEX);
   return (defaultMatch || namespaceMatch)?.[2] ?? null;
@@ -68,13 +100,13 @@ async function extractComponentUrl(doc) {
   if (inlineHydrationScript?.textContent) {
     return extractModulePathFromCode(inlineHydrationScript.textContent);
   }
-  const hydrationScript = scripts.find((s) => isReactPageHydrationAsset(s.src ?? ""));
+  const hydrationScript = doc.querySelector(PAGE_BOOTSTRAP_SELECTOR) ?? scripts.find((s) => isReactPageHydrationAssetSrc(s.src ?? ""));
   if (!hydrationScript?.src) return null;
   try {
     const scriptUrl = addCacheBuster(hydrationScript.src);
     const res = await fetch(scriptUrl);
     const code = await res.text();
-    return extractModulePathFromCode(code);
+    return extractModulePathFromCode(code, hydrationScript.src);
   } catch {
     return null;
   }
@@ -107,9 +139,9 @@ async function fetchPageDocument(url, options = {}) {
     return null;
   }
 }
-async function loadPageModuleFromDocument(doc, finalPath) {
+async function loadPageModuleFromDocument(doc, finalPath, options = {}) {
   const props = extractProps(doc);
-  const componentUrl = await extractComponentUrl(doc);
+  const componentUrl = options.moduleUrlOverride ?? await extractComponentUrl(doc);
   if (!componentUrl) {
     if (isReactRouteDocument(doc)) {
       console.error("[EcoRouter] Could not find component URL");
@@ -140,6 +172,7 @@ export {
   extractProps,
   fetchPageDocument,
   getInterceptDecision,
+  isSamePageHashNavigationHref,
   loadPageModule,
   loadPageModuleFromDocument,
   shouldInterceptClick

package/src/router.d.ts

@@ -31,7 +31,9 @@ export declare function clearLayoutCache(): void;
  * Must be a child of {@link EcoRouter}. When `persistLayouts` is enabled,
  * shared layouts remain mounted across navigations. When the server serialized
  * request `locals` for hydration, the same `locals` object is passed to the
- * layout on the client so the hydrated tree matches SSR.
+ * layout on the client so the hydrated tree matches SSR. Refresh-style updates
+ * may still replace the cached layout implementation when the router marks the
+ * page state with `refreshPersistedLayout`.
  *
  * @example
  * ```tsx