@ecopages/react-router 0.2.0-alpha.22 → 0.2.0-alpha.25

package/CHANGELOG.md

@@ -8,6 +8,8 @@ All notable changes to `@ecopages/react-router` are documented here.
 
 ### Bug Fixes
 
+- Extended page-module extraction to honor explicit hydration markers and self-owned React page entry bundles during navigation.
+- Fixed current-page reloads to accept HMR module overrides so persisted-layout refreshes import the rebuilt active page entry.
 - 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/react-router",
-  "version": "0.2.0-alpha.22",
+  "version": "0.2.0-alpha.25",
   "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.22",
-    "@ecopages/react": "0.2.0-alpha.22"
+    "@ecopages/core": "0.2.0-alpha.25",
+    "@ecopages/react": "0.2.0-alpha.25"
   },
   "dependencies": {
     "react": "^19",

package/src/head-morpher.js

@@ -1,3 +1,4 @@
+import { isReactRouterPageBootstrapAssetSrc } from "./hydration-assets.js";
 const PRESERVE_SELECTORS = ['script[type="importmap"]', "meta[charset]", "[data-eco-persist]"];
 const RERUN_SRC_ATTR = "data-eco-rerun-src";
 let rerunNonce = 0;
@@ -38,7 +39,7 @@ function isRerunScript(el) {
 }
 function isHydrationScript(el) {
   const src = el.getAttribute("src");
-  return !!src && src.includes("hydration.js") && src.includes("ecopages-react");
+  return !!src && isReactRouterPageBootstrapAssetSrc(src);
 }
 function getHeadElementKey(el) {
   const tag = el.tagName.toLowerCase();

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,6 +23,16 @@ 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;
 } | {
@@ -69,7 +79,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,8 +1,6 @@
 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 getInterceptDecision(event, link, options) {
   if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
     return { shouldIntercept: false, reason: "modified-click" };
@@ -28,7 +26,29 @@ 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 = /module\s*:\s*['"]([^'"]+)['"]/;
+const PAGE_MODULE_IDENTIFIER_REGEX = /module\s*:\s*([A-Za-z_$][\w$]*)\s*,/;
+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 +88,13 @@ async function extractComponentUrl(doc) {
   if (inlineHydrationScript?.textContent) {
     return extractModulePathFromCode(inlineHydrationScript.textContent);
   }
-  const hydrationScript = scripts.find((s) => isReactPageHydrationAsset(s.src ?? ""));
+  const hydrationScript = 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 +127,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");

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

package/src/router.js

@@ -64,7 +64,7 @@ const PageContent = () => {
     }
     return null;
   }
-  const { Component: Page, props } = pageContext;
+  const { Component: Page, props, refreshPersistedLayout } = pageContext;
   const Layout = getLayoutFromPage(Page);
   const pageElement = createElement(Page, props);
   const layoutProps = props?.locals ? { locals: props.locals } : null;
@@ -76,7 +76,7 @@ const PageContent = () => {
     const layoutConfig = Layout.config;
     const layoutKeyRaw = layoutConfig?.__eco?.id || Layout.displayName || Layout.name || "layout";
     const layoutKey = normalizeLayoutKey(layoutKeyRaw);
-    if (!layoutCache.has(layoutKey)) {
+    if (!layoutCache.has(layoutKey) || refreshPersistedLayout && layoutCache.get(layoutKey) !== Layout) {
       layoutCache.set(layoutKey, Layout);
     }
     const CachedLayout = layoutCache.get(layoutKey);
@@ -114,7 +114,7 @@ function useNavigationCoordinator(navigate, activeNavigationRef, isNavigatingRef
           clearLayoutCache();
         }
         const currentUrl = window.location.pathname + window.location.search;
-        await navigate(currentUrl);
+        await navigate(currentUrl, { moduleUrlOverride: request?.moduleUrl });
       },
       cleanupBeforeHandoff: async () => {
         runtimeActiveRef.current = false;
@@ -136,7 +136,11 @@ function useNavigationCoordinator(navigate, activeNavigationRef, isNavigatingRef
 }
 const EcoRouter = ({ page, pageProps, options: userOptions, children }) => {
   const options = useMemo(() => ({ ...DEFAULT_OPTIONS, ...userOptions }), [userOptions]);
-  const [currentPage, setCurrentPage] = useState({ Component: page, props: pageProps });
+  const [currentPage, setCurrentPage] = useState({
+    Component: page,
+    props: pageProps,
+    refreshPersistedLayout: false
+  });
   const [isNavigating, setIsNavigating] = useState(false);
   const pendingRenderRef = useRef(null);
   const activeNavigationRef = useRef(null);
@@ -145,13 +149,12 @@ const EcoRouter = ({ page, pageProps, options: userOptions, children }) => {
   const pendingPointerNavigationRef = useRef(null);
   const pendingHoverNavigationRef = useRef(null);
   const queuedNavigationHrefRef = useRef(null);
-  const pendingScrollRestoreRef = useRef(null);
   const previousUrlRef = useRef(typeof window !== "undefined" ? window.location.href : "");
   useEffect(() => {
     isNavigatingRef.current = isNavigating;
   }, [isNavigating]);
   useEffect(() => {
-    setCurrentPage({ Component: page, props: pageProps });
+    setCurrentPage({ Component: page, props: pageProps, refreshPersistedLayout: true });
   }, [page, pageProps]);
   useEffect(() => {
     applyViewTransitionNames();
@@ -182,15 +185,15 @@ const EcoRouter = ({ page, pageProps, options: userOptions, children }) => {
       });
       previousUrlRef.current = url.href;
     }
-    if (pendingScrollRestoreRef.current) {
-      const { url: targetUrl, isPopState } = pendingScrollRestoreRef.current;
-      restoreScrollPositions(targetUrl, isPopState);
-      pendingScrollRestoreRef.current = null;
-    }
   }, [currentPage, options.scrollBehavior, options.smoothScroll]);
   const navigate = useCallback(
     async (url, navigationOptions = {}) => {
-      const { isPopState = false, pushHistory = false, skipViewTransition = false } = navigationOptions;
+      const {
+        isPopState = false,
+        pushHistory = false,
+        skipViewTransition = false,
+        moduleUrlOverride
+      } = navigationOptions;
       const navigationRuntime = getEcoNavigationRuntime(window);
       const navigation = navigationRuntime.beginNavigationTransaction();
       activeNavigationRef.current = navigation;
@@ -212,24 +215,25 @@ const EcoRouter = ({ page, pageProps, options: userOptions, children }) => {
           window.location.href = url;
           return;
         }
-        const result = await loadPageModuleFromDocument(fetchedPage.doc, fetchedPage.finalPath);
+        const result = await loadPageModuleFromDocument(fetchedPage.doc, fetchedPage.finalPath, {
+          moduleUrlOverride
+        });
         if (isStale()) return;
         if (result) {
           const { Component, props, doc, finalPath, moduleUrl } = result;
-          const nextPage = { Component, props };
+          const nextPage = { Component, props, refreshPersistedLayout: Boolean(moduleUrlOverride) };
           const { cleanup: cleanupHead, flushRerunScripts } = await morphHead(doc);
           if (isStale()) {
             cleanupHead();
             return;
           }
           applyViewTransitionNames();
+          saveScrollPositions();
           if (pushHistory) {
             window.history.pushState(null, "", finalPath);
           } else if (finalPath !== url) {
             window.history.replaceState(null, "", finalPath);
           }
-          saveScrollPositions();
-          pendingScrollRestoreRef.current = { url, isPopState };
           if (!skipViewTransition && options.viewTransitions && document.startViewTransition) {
             pendingRenderRef.current?.resolve();
             const renderDfd = createDeferred();
@@ -260,6 +264,7 @@ const EcoRouter = ({ page, pageProps, options: userOptions, children }) => {
                   flushRerunScripts();
                   cleanupHead();
                   applyViewTransitionNames();
+                  restoreScrollPositions(finalPath, isPopState);
                 } finally {
                   resolve();
                 }
@@ -284,6 +289,7 @@ const EcoRouter = ({ page, pageProps, options: userOptions, children }) => {
             flushRerunScripts();
             cleanupHead();
             applyViewTransitionNames();
+            restoreScrollPositions(finalPath, isPopState);
           }
         } else {
           if (isStale()) return;

package/src/scroll-persist.js

@@ -28,19 +28,27 @@ function restoreScrollPositions(targetUrl, isPopState) {
     currentScrollSnapshot = null;
     return;
   }
-  requestAnimationFrame(() => {
+  const restore = (remainingAttempts) => {
     requestAnimationFrame(() => {
+      const restoredKeys = /* @__PURE__ */ new Set();
       document.querySelectorAll(PERSIST_SELECTOR).forEach((el) => {
         const key = getElementKey(el);
-        if (key && positions.has(key)) {
-          const pos = positions.get(key);
-          el.scrollTop = pos.top;
-          el.scrollLeft = pos.left;
+        if (!key || !positions.has(key)) {
+          return;
         }
+        const pos = positions.get(key);
+        el.scrollTop = pos.top;
+        el.scrollLeft = pos.left;
+        restoredKeys.add(key);
       });
-      currentScrollSnapshot = null;
+      if (restoredKeys.size === positions.size || remainingAttempts <= 1) {
+        currentScrollSnapshot = null;
+        return;
+      }
+      setTimeout(() => restore(remainingAttempts - 1), 50);
     });
-  });
+  };
+  restore(20);
 }
 function getScrollPositions(url) {
   return urlScrollStore.get(url);