npm - @ecopages/react-router - Versions diffs - 0.2.0-alpha.5 → 0.2.0-alpha.7 - Mend

@ecopages/react-router 0.2.0-alpha.5 → 0.2.0-alpha.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -6,7 +6,14 @@ All notable changes to `@ecopages/react-router` are documented here.
 ## [UNRELEASED] — TBD
+### 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.
 ### Refactoring
-- Updated `package.json` dependencies to align with the new core adapter and esbuild build adapter versions.
-- Internal peer dependency declarations updated for React 18+ and the new `@ecopages/core` API surface.
+- Routed browser handoff and current-page reloads through the shared navigation coordinator.
+- Updated package metadata for the current core, esbuild adapter, and React peer dependency surface.

package/README.md CHANGED Viewed

@@ -1,46 +1,57 @@
 # @ecopages/react-router
-Client-side SPA router for EcoPages React applications. Enables single-page application navigation while preserving full SSR benefits.
+Client-side SPA router for Ecopages React applications. Features single-page application navigation while preserving all the benefits of Server-Side Rendering (SSR).
+## Features
+- **SSR preserved**: Initial loads are fully server-rendered.
+- **Opt-in via config**: A single line in your config enables SPA navigation across all pages.
+- **Layout persistence**: Shared layouts stay mounted while page content swaps.
+- **Standard links**: Works with regular `<a>` tags.
+- **Head sync**: Automatically updates document metadata `<head>` during navigation.
+- **View Transitions**: Built-in support for the browser View Transitions API.
+## Cross-Runtime Handoff
+`@ecopages/react-router` only performs SPA updates for React-managed documents. When a navigation resolves to a non-React document, it will:
+- hand the already-fetched HTML document to `@ecopages/browser-router` when browser-router is registered on the page
+- fall back to a normal document navigation when browser-router is not present
+This keeps React-router focused on React rendering while still allowing mixed React and non-React pages to transition without a second fetch when browser-router is active.
 ## Installation
 ```bash
-bun add @ecopages/react-router
+bunx jsr add @ecopages/react-router
 ```
 ## Quick Start
-Add the router adapter to your `eco.config.ts`:
+Pass the router adapter to the React plugin in your `eco.config.ts`:
 ```typescript
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 import { reactPlugin } from '@ecopages/react';
 import { ecoRouter } from '@ecopages/react-router';
 const config = await new ConfigBuilder()
-	.setRootDir(import.meta.dir)
+	.setRootDir(import.meta.dirname)
 	.setIntegrations([reactPlugin({ router: ecoRouter() })])
 	.build();
 export default config;
 ```
-That's it! All pages now have SPA navigation enabled.
-## Features
+SPA navigation is now enabled for all React pages in your project.
-- **Opt-in via config** - Single line enables SPA for all pages
-- **SSR preserved** - Full server-side rendering on initial load
-- **Layout persistence** - Layouts stay mounted, only page content swaps
-- **Standard links** - Works with regular `<a>` tags
-- **Head sync** - Automatically updates title, meta, and stylesheets
-- **Pluggable** - Extensible adapter pattern
+If your site mixes React pages with non-React pages, you can also run `@ecopages/browser-router` on the non-React shell. React-router will hand off non-React navigations to browser-router when it is available.
 ## Usage
 ### Layouts (Optional)
-Use `config.layout` for persistent UI across navigations:
+Configure your page with a layout to keep UI components (like headers/navs) mounted across navigations:
 ```tsx
 // src/layouts/base-layout.tsx
@@ -65,6 +76,8 @@ export default HomePage;
 ### Links
+Standard relative links are intercepted natively. To bypass the router and force a hard reload, use the `data-eco-reload` attribute.
 ```tsx
 // SPA navigation (intercepted)
 <a href="/about">About</a>
@@ -89,39 +102,21 @@ const MyComponent = () => {
 };
 ```
-### View Transitions
-The router automatically supports the [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) for smooth page transitions.
+## View Transitions
-#### Lifecycle
+The router automatically integrates with the [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API).
-When a navigation occurs with View Transitions enabled:
-1.  **Snapshot**: The browser captures the current state (screenshot) of the page.
-2.  **Update**: React processes the state change and renders the new page.
-3.  **Animate**: The browser animates from the old snapshot to the new live state.
-The router uses a deferred promise mechanism to ensure React has fully finished rendering the new content before telling the browser to start the animation phase.
-#### Shared Element Transitions
-To animate elements between pages (e.g., a thumbnail becoming a hero image), use the `data-view-transition` attribute. Ensure the value is unique to the specific element being transitioned and matches on both pages.
+To animate elements between pages using Shared Element Transitions, mark them with a unique `data-view-transition` id that matches across both pages:
 ```tsx
-// List Page (Source)
-<img
-  src={post.image}
-  data-view-transition={`hero-${post.id}`}
-/>
-// Detail Page (Destination)
-<img
-  src={post.image}
-  data-view-transition={`hero-${post.id}`}
-/>
+// List Page
+<img src={post.image} data-view-transition={`hero-${post.id}`} />
+// Detail Page
+<img src={post.image} data-view-transition={`hero-${post.id}`} />
 ```
-By default, the router applies a **clean morph** animation (disabling the default cross-fade ghosting). If you prefer the standard browser cross-fade, you can opt-out:
+By default, we impose a "clean morph", disabling default cross-fade ghosting. To use standard crossfades on elements, opt-out:
 ```tsx
 <div data-view-transition="my-hero" data-view-transition-animate="fade">
@@ -129,84 +124,15 @@ By default, the router applies a **clean morph** animation (disabling the defaul
 </div>
 ```
-#### Cross-Fade
-By default, the router provides a smooth cross-fade for the root content. You can customize this by overriding the default view transition CSS:
-```css
-::view-transition-old(root),
-::view-transition-new(root) {
-	animation-duration: 0.5s;
-}
-```
 ## How It Works
-The router uses an **HTML-First** navigation strategy to ensure consistency with Server-Side Rendering (SSR).
-1.  **SSR**: Server renders full HTML for the initial page load.
-2.  **Hydration**: Client hydrates, router attaches to the document.
-3.  **Navigation**: On link click:
-    - **Fetch**: Requests the full HTML of the target page (just like a standard browser navigation).
-    - **Parse**: Extracts the page component URL and serialized props from the HTML.
-    - **Preload**: Dynamically imports the new page component.
-    - **Transition**:
-        - Calls `document.startViewTransition()`.
-        - Updates the document head (title, meta, styles).
-        - Updates the React state to render the new page component.
-        - Waits for React commit (useEffect).
-    - **Resolve**: View Transition finishes, browser plays the animation.
-## API
-### `ecoRouter()`
-Creates a router adapter for the React plugin.
-```typescript
-reactPlugin({ router: ecoRouter() });
-```
-### `useRouter()`
-Hook for programmatic navigation.
-```typescript
-const { navigate, isPending } = useRouter();
-```
-### Link Behavior
-Links are **not** intercepted when:
-- Modifier keys held (Ctrl, Cmd, Shift, Alt)
-- Has `target="_blank"` or `download` attribute
-- Has `data-eco-reload` attribute
-- Points to different origin
-- Starts with `#` or `javascript:`
-## Architecture
-The router uses a pluggable adapter pattern:
-```typescript
-interface ReactRouterAdapter {
-	name: string;
-	bundle: { importPath; outputName; externals };
-	importMapKey: string;
-	components: { router; pageContent };
-	getRouterProps(page, props): string;
-}
-```
-This allows custom router implementations while keeping integration simple.
-## Compatibility
-- React 18.x or 19.x
-- Modern browsers with ES modules
-- EcoPages with React integration
-## License
+The router relies on **HTML-First** navigation to sync perfectly with SSR:
-MIT
+1. **SSR**: Initial page arrives completely rendered.
+2. **Hydration**: Client hydrates and the router attaches.
+3. **Navigation**: On click, the router:
+    - Fetches the raw HTML of the next route.
+    - Extracts page-level serialized props and metadata.
+    - Preloads the next page component via dynamic import.
+    - Updates React state, syncs `<head>`, and triggers `startViewTransition`.
+    - The React graph reconciles and the animation plays.

package/package.json CHANGED Viewed

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

package/src/head-morpher.js CHANGED Viewed

@@ -1,4 +1,36 @@
 const PRESERVE_SELECTORS = ['script[type="importmap"]', "meta[charset]", "[data-eco-persist]"];
+function isNonExecutableHeadScript(el) {
+  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) {
+  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.src) {
+    return false;
+  }
+  return !isNonExecutableHeadScript(el);
+}
 function getHeadElementKey(el) {
   const tag = el.tagName.toLowerCase();
   switch (tag) {
@@ -18,6 +50,8 @@ function getHeadElementKey(el) {
     }
     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;
       return src ? `script:${src}` : null;
     }
@@ -62,6 +96,8 @@ async function morphHead(newDocument) {
       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;
     }
@@ -78,7 +114,7 @@ async function morphHead(newDocument) {
   for (const [key, el] of currentElements) {
     if (!newElements.has(key)) {
       const shouldPreserve = PRESERVE_SELECTORS.some((sel) => el.matches(sel));
-      if (!shouldPreserve) {
+      if (!shouldPreserve && !shouldPersistExecutableInlineHeadScript(el)) {
         elementsToRemove.push(el);
       }
     }

package/src/head-morpher.ts CHANGED Viewed

@@ -6,6 +6,46 @@
 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.
@@ -33,6 +73,8 @@ function getHeadElementKey(el: Element): string | 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;
 		}
@@ -122,6 +164,8 @@ export async function morphHead(newDocument: Document): Promise<() => void> {
 			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;
 		}
@@ -151,7 +195,7 @@ export async function morphHead(newDocument: Document): Promise<() => void> {
 	for (const [key, el] of currentElements) {
 		if (!newElements.has(key)) {
 			const shouldPreserve = PRESERVE_SELECTORS.some((sel) => el.matches(sel));
-			if (!shouldPreserve) {
+			if (!shouldPreserve && !shouldPersistExecutableInlineHeadScript(el)) {
 				elementsToRemove.push(el);
 			}
 		}

package/src/navigation.d.ts CHANGED Viewed

@@ -8,6 +8,21 @@ export type PageState = {
     Component: ComponentType<any>;
     props: Record<string, any>;
 };
+export type LoadedPageModule = {
+    Component: ComponentType<any>;
+    props: Record<string, any>;
+    doc: Document;
+    finalPath: string;
+    moduleUrl: string;
+};
+export type FetchedPageDocument = {
+    doc: Document;
+    finalPath: string;
+    html: string;
+};
+type LoadPageModuleOptions = {
+    signal?: AbortSignal;
+};
 export type InterceptDecision = {
     shouldIntercept: true;
 } | {
@@ -26,7 +41,7 @@ export type InterceptDecision = {
  */
 export declare function getInterceptDecision(event: MouseEvent, link: HTMLAnchorElement, options: Required<EcoRouterOptions>): InterceptDecision;
 /**
- * Extracts serialized page props from window.__ECO_PAGE__ or fetched document.
+ * Extracts serialized page props from window.__ECO_PAGES__.page or fetched document.
  * For current document, returns props set by hydration script.
  * For fetched documents, parses the JSON script tag directly.
  */
@@ -34,7 +49,7 @@ export declare function extractProps(doc: Document): Record<string, any>;
 /**
  * Extracts component module URL using multi-tier strategy.
  *
- * 1. Read from window.__ECO_PAGE__.module (for current document)
+ * 1. Read from window.__ECO_PAGES__.page.module (for current document)
  * 2. Parse inline hydration script with regex (for fetched documents)
  * 3. Fetch and parse external hydration script (final fallback)
  *
@@ -52,14 +67,12 @@ export declare function extractComponentUrl(doc: Document): Promise<string | nul
  * @param url - The URL to load
  * @returns Object with Component, props, doc, and finalPath, or null on error
  */
-export declare function loadPageModule(url: string): Promise<{
-    Component: ComponentType<any>;
-    props: Record<string, any>;
-    doc: Document;
-    finalPath: string;
-} | null>;
+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>;
 /**
  * Convenience wrapper around getInterceptDecision that returns a boolean.
  * Use getInterceptDecision directly when you need the reason for debugging.
  */
 export declare function shouldInterceptClick(event: MouseEvent, link: HTMLAnchorElement, options: Required<EcoRouterOptions>): boolean;
+export {};

package/src/navigation.js CHANGED Viewed

@@ -1,3 +1,8 @@
+import { getEcoDocumentOwner } from "@ecopages/core/router/navigation-coordinator";
+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" };
@@ -16,8 +21,8 @@ function getInterceptDecision(event, link, options) {
   return { shouldIntercept: true };
 }
 function extractComponentUrlFromMarker(doc) {
-  if (doc === document && window.__ECO_PAGE__?.module) {
-    return window.__ECO_PAGE__.module;
+  if (doc === document && window.__ECO_PAGES__?.page?.module) {
+    return window.__ECO_PAGES__.page.module;
   }
   return null;
 }
@@ -29,10 +34,10 @@ function extractModulePathFromCode(code) {
   return (defaultMatch || namespaceMatch)?.[2] ?? null;
 }
 function extractProps(doc) {
-  if (doc === document && window.__ECO_PAGE__?.props) {
-    return window.__ECO_PAGE__.props;
+  if (doc === document && window.__ECO_PAGES__?.page?.props) {
+    return window.__ECO_PAGES__.page.props;
   }
-  const propsScript = doc.getElementById("__ECO_PAGE_DATA__");
+  const propsScript = doc.getElementById(ROUTER_PROPS_SCRIPT_ID);
   if (propsScript?.textContent) {
     try {
       return JSON.parse(propsScript.textContent);
@@ -43,6 +48,9 @@ function extractProps(doc) {
   }
   return {};
 }
+function isReactRouteDocument(doc) {
+  return getEcoDocumentOwner(doc) === "react-router";
+}
 function addCacheBuster(url) {
   if (import.meta.env?.MODE === "production" || import.meta.env?.PROD) {
     return url;
@@ -55,12 +63,12 @@ async function extractComponentUrl(doc) {
   if (markerUrl) return markerUrl;
   const scripts = Array.from(doc.querySelectorAll("script"));
   const inlineHydrationScript = scripts.find(
-    (s) => !s.src && !!s.textContent && s.textContent.includes("__ECO_PAGE__") && s.textContent.includes("hydrateRoot") && s.textContent.includes("import")
+    (s) => !s.src && !!s.textContent && s.textContent.includes("__ECO_PAGES__") && s.textContent.includes("hydrateRoot") && s.textContent.includes("import")
   );
   if (inlineHydrationScript?.textContent) {
     return extractModulePathFromCode(inlineHydrationScript.textContent);
   }
-  const hydrationScript = scripts.find((s) => s.src?.includes("hydration.js") && s.src?.includes("ecopages-react"));
+  const hydrationScript = scripts.find((s) => isReactPageHydrationAsset(s.src ?? ""));
   if (!hydrationScript?.src) return null;
   try {
     const scriptUrl = addCacheBuster(hydrationScript.src);
@@ -71,50 +79,68 @@ async function extractComponentUrl(doc) {
     return null;
   }
 }
-async function loadPageModule(url) {
+async function loadPageModule(url, options = {}) {
+  const fetchedPage = await fetchPageDocument(url, options);
+  if (!fetchedPage) {
+    return null;
+  }
+  return loadPageModuleFromDocument(fetchedPage.doc, fetchedPage.finalPath);
+}
+async function fetchPageDocument(url, options = {}) {
   try {
-    const res = await fetch(url);
+    const res = await fetch(url, {
+      signal: options.signal,
+      headers: {
+        Accept: "text/html"
+      }
+    });
     const html = await res.text();
     const finalUrl = new URL(res.url || url, window.location.origin);
     const finalPath = finalUrl.pathname + finalUrl.search;
     const doc = new DOMParser().parseFromString(html, "text/html");
-    const props = extractProps(doc);
-    const componentUrl = await extractComponentUrl(doc);
-    if (!componentUrl) {
-      console.error("[EcoRouter] Could not find component URL");
-      return null;
-    }
-    const moduleUrl = addCacheBuster(componentUrl);
-    const module = await import(
-      /* @vite-ignore */
-      moduleUrl
-    );
-    const rawComponent = module.Content || module.default?.Content || module.default;
-    const config = module.config || rawComponent?.config;
-    if (!rawComponent) {
-      console.error("[EcoRouter] No component found in module");
+    return { doc, finalPath, html };
+  } catch (e) {
+    if (e instanceof DOMException && e.name === "AbortError") {
       return null;
     }
-    if (config && !rawComponent.config) {
-      rawComponent.config = config;
-    }
-    window.__ECO_PAGE__ = {
-      module: componentUrl,
-      props
-    };
-    return { Component: rawComponent, props, doc, finalPath };
-  } catch (e) {
     console.error("[EcoRouter] Navigation failed:", e);
     return null;
   }
 }
+async function loadPageModuleFromDocument(doc, finalPath) {
+  const props = extractProps(doc);
+  const componentUrl = await extractComponentUrl(doc);
+  if (!componentUrl) {
+    if (isReactRouteDocument(doc)) {
+      console.error("[EcoRouter] Could not find component URL");
+    }
+    return null;
+  }
+  const moduleUrl = addCacheBuster(componentUrl);
+  const module = await import(
+    /* @vite-ignore */
+    moduleUrl
+  );
+  const rawComponent = module.Content || module.default?.Content || module.default;
+  const config = module.config || rawComponent?.config;
+  if (!rawComponent) {
+    console.error("[EcoRouter] No component found in module");
+    return null;
+  }
+  if (config && !rawComponent.config) {
+    rawComponent.config = config;
+  }
+  return { Component: rawComponent, props, doc, finalPath, moduleUrl: componentUrl };
+}
 function shouldInterceptClick(event, link, options) {
   return getInterceptDecision(event, link, options).shouldIntercept;
 }
 export {
   extractComponentUrl,
   extractProps,
+  fetchPageDocument,
   getInterceptDecision,
   loadPageModule,
+  loadPageModuleFromDocument,
   shouldInterceptClick
 };