@ecopages/browser-router 0.2.0-alpha.3 → 0.2.0-alpha.30

package/src/client/eco-router.js

@@ -1,14 +1,31 @@
-import { DEFAULT_OPTIONS } from "./types.js";
+import { getEcoNavigationRuntime } from "@ecopages/core/router/navigation-coordinator";
+import {
+  getAnchorFromNavigationEvent,
+  recoverPendingNavigationHref
+} from "@ecopages/core/router/link-intent";
+import { DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC, DEFAULT_OPTIONS } from "./types.js";
+import { syncDocumentElementAttributes } from "./document-element-sync.js";
 import { DomSwapper, ScrollManager, ViewTransitionManager, PrefetchManager } from "./services/index.js";
 class EcoRouter {
   options;
-  abortController = null;
+  unregisterNavigationRuntime = null;
+  started = false;
+  pendingNavigations = 0;
+  pendingPointerNavigation = null;
+  pendingHoverNavigation = null;
+  queuedNavigationHref = null;
   domSwapper;
   scrollManager;
   viewTransitionManager;
   prefetchManager = null;
   constructor(options = {}) {
-    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.options = {
+      ...DEFAULT_OPTIONS,
+      ...options,
+      documentElementAttributesToSync: [
+        ...options.documentElementAttributesToSync ?? DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC
+      ]
+    };
     this.domSwapper = new DomSwapper(this.options.persistAttribute);
     this.scrollManager = new ScrollManager(this.options.scrollBehavior, this.options.smoothScroll);
     this.viewTransitionManager = new ViewTransitionManager(this.options.viewTransitions);
@@ -19,8 +36,154 @@ class EcoRouter {
       });
     }
     this.handleClick = this.handleClick.bind(this);
+    this.handleHoverIntent = this.handleHoverIntent.bind(this);
+    this.handlePointerDown = this.handlePointerDown.bind(this);
     this.handlePopState = this.handlePopState.bind(this);
   }
+  getLinkFromEvent(event) {
+    return getAnchorFromNavigationEvent(event, this.options.linkSelector);
+  }
+  canInterceptLink(event, link) {
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return null;
+    if (event.button !== 0) return null;
+    const target = link.getAttribute("target");
+    if (target && target !== "_self") return null;
+    if (link.hasAttribute(this.options.reloadAttribute)) return null;
+    if (link.hasAttribute("download")) return null;
+    const href = link.getAttribute("href");
+    if (!href) return null;
+    if (href.startsWith("#")) return null;
+    if (href.startsWith("javascript:")) return null;
+    const url = new URL(href, window.location.origin);
+    if (!this.isSameOrigin(url)) return null;
+    if (url.hash && url.pathname === window.location.pathname && url.search === window.location.search) {
+      return null;
+    }
+    return href;
+  }
+  getRecoveredPointerHref() {
+    const href = recoverPendingNavigationHref(
+      this.pendingPointerNavigation,
+      this.pendingNavigations > 0,
+      performance.now()
+    );
+    if (!href) {
+      this.pendingPointerNavigation = null;
+    }
+    return href;
+  }
+  getRecoveredHoverHref() {
+    const href = recoverPendingNavigationHref(
+      this.pendingHoverNavigation,
+      this.pendingNavigations > 0,
+      performance.now()
+    );
+    if (!href) {
+      this.pendingHoverNavigation = null;
+    }
+    return href;
+  }
+  isAnotherNavigationRuntimeActive() {
+    const ownerState = getEcoNavigationRuntime(window).getOwnerState();
+    return ownerState.owner !== "none" && ownerState.owner !== "browser-router" && ownerState.canHandleSpaNavigation;
+  }
+  getDocumentOwner(doc) {
+    return getEcoNavigationRuntime(window).resolveDocumentOwner(doc, "browser-router");
+  }
+  adoptDocumentOwner(doc) {
+    getEcoNavigationRuntime(window).adoptDocumentOwner(doc, "browser-router");
+  }
+  syncDocumentElementAttributes(newDocument) {
+    syncDocumentElementAttributes(document, newDocument, this.options.documentElementAttributesToSync);
+  }
+  reloadDocument(url) {
+    window.location.assign(url.href);
+  }
+  /**
+   * Commits a fully fetched document into the live page.
+   *
+   * When browser-router accepts a handoff from another runtime, it delays source
+   * runtime cleanup until the incoming document has been prepared and is ready to
+   * commit. That ordering avoids the blank-page window we previously hit when a
+   * delegated navigation went stale after the source runtime had already torn
+   * itself down.
+   */
+  async commitDocumentNavigation(url, direction, newDocument, options = {}) {
+    const previousUrl = new URL(window.location.href);
+    const navigationRuntime = getEcoNavigationRuntime(window);
+    const isStaleNavigation = options.isStaleNavigation ?? (() => false);
+    const currentDocumentOwner = navigationRuntime.resolveDocumentOwner(document, "browser-router");
+    const newDocumentOwner = navigationRuntime.resolveDocumentOwner(newDocument, "browser-router");
+    const activeOwner = navigationRuntime.getOwnerState().owner;
+    const shouldCleanupCurrentOwner = currentDocumentOwner !== newDocumentOwner && currentDocumentOwner !== "browser-router" && activeOwner === currentDocumentOwner;
+    let shouldReload = false;
+    const beforeSwapEvent = {
+      url,
+      direction,
+      newDocument,
+      reload: () => {
+        shouldReload = true;
+      }
+    };
+    document.dispatchEvent(new CustomEvent("eco:before-swap", { detail: beforeSwapEvent }));
+    if (isStaleNavigation()) return;
+    if (shouldReload) {
+      if (shouldCleanupCurrentOwner) {
+        await navigationRuntime.cleanupOwner(currentDocumentOwner);
+      }
+      if (isStaleNavigation()) return;
+      this.reloadDocument(url);
+      return;
+    }
+    const useViewTransitions = this.options.viewTransitions;
+    await this.domSwapper.preloadStylesheets(newDocument);
+    if (isStaleNavigation()) return;
+    if (shouldCleanupCurrentOwner) {
+      await navigationRuntime.cleanupOwner(currentDocumentOwner);
+    }
+    if (isStaleNavigation()) return;
+    const commitSwap = () => {
+      if (isStaleNavigation()) return;
+      if (this.options.updateHistory && direction === "forward") {
+        window.history.pushState({}, "", url.href);
+      } else if (direction === "replace") {
+        window.history.replaceState({}, "", url.href);
+      }
+      this.syncDocumentElementAttributes(newDocument);
+      this.domSwapper.morphHead(newDocument);
+      if (useViewTransitions && !this.domSwapper.shouldReplaceBodyForRerunScripts()) {
+        this.domSwapper.morphBody(newDocument);
+      } else {
+        this.domSwapper.replaceBody(newDocument);
+      }
+      this.domSwapper.flushRerunScripts();
+      this.scrollManager.handleScroll(url, previousUrl);
+    };
+    if (useViewTransitions) {
+      await this.viewTransitionManager.transition(commitSwap);
+    } else {
+      commitSwap();
+    }
+    if (isStaleNavigation()) return;
+    navigationRuntime.adoptDocumentOwner(newDocument, "browser-router");
+    const afterSwapEvent = {
+      url,
+      direction
+    };
+    document.dispatchEvent(new CustomEvent("eco:after-swap", { detail: afterSwapEvent }));
+    this.prefetchManager?.observeNewLinks();
+    if (options.html) {
+      this.prefetchManager?.cacheVisitedPage(url.href, options.html);
+    }
+    requestAnimationFrame(() => {
+      if (isStaleNavigation()) return;
+      document.dispatchEvent(
+        new CustomEvent("eco:page-load", {
+          detail: { url, direction }
+        })
+      );
+    });
+  }
   /**
    * Starts the router and begins intercepting navigation.
    *
@@ -28,30 +191,87 @@ class EcoRouter {
    * back/forward buttons. Also starts the prefetch manager if configured.
    */
   start() {
-    document.addEventListener("click", this.handleClick);
+    if (this.started) {
+      return;
+    }
+    const navigationRuntime = getEcoNavigationRuntime(window);
+    document.addEventListener("mouseover", this.handleHoverIntent, true);
+    document.addEventListener("pointerover", this.handleHoverIntent, true);
+    document.addEventListener("mousemove", this.handleHoverIntent, true);
+    document.addEventListener("pointermove", this.handleHoverIntent, true);
+    document.addEventListener("pointerdown", this.handlePointerDown, true);
+    document.addEventListener("click", this.handleClick, true);
     window.addEventListener("popstate", this.handlePopState);
     this.prefetchManager?.start();
-    const windowWithHmr = window;
-    windowWithHmr.__ecopages_reload_current_page__ = async (options) => {
-      const currentUrl = window.location.pathname + window.location.search;
-      if (options.clearCache) {
-        this.prefetchManager?.invalidate(currentUrl);
+    this.unregisterNavigationRuntime?.();
+    this.unregisterNavigationRuntime = navigationRuntime.register({
+      owner: "browser-router",
+      navigate: async (request) => {
+        await this.performNavigation(
+          new URL(request.href, window.location.origin),
+          request.direction ?? "forward"
+        );
+        return true;
+      },
+      handoffNavigation: async (request) => {
+        const { isStaleNavigation, complete } = this.beginNavigationTransaction();
+        if (isStaleNavigation()) return true;
+        try {
+          await this.commitDocumentNavigation(
+            new URL(request.finalHref ?? request.href, window.location.origin),
+            request.direction ?? "forward",
+            request.document,
+            { html: request.html, isStaleNavigation }
+          );
+        } finally {
+          complete();
+        }
+        return true;
+      },
+      reloadCurrentPage: async (request) => {
+        if (this.pendingNavigations > 0) return;
+        const currentUrl = window.location.pathname + window.location.search;
+        if (request?.clearCache) {
+          this.prefetchManager?.invalidate(currentUrl);
+        }
+        await this.performNavigation(new URL(currentUrl, window.location.origin), "replace");
+      },
+      cleanupBeforeHandoff: async () => {
+        this.cancelNavigationTransaction();
       }
-      await this.performNavigation(new URL(currentUrl, window.location.origin), "replace");
-    };
+    });
+    this.adoptDocumentOwner(document);
     const initialHtml = document.documentElement.outerHTML;
     this.prefetchManager?.cacheVisitedPage(window.location.href, initialHtml);
+    this.started = true;
   }
   /**
    * Stops the router and cleans up all event listeners.
    * After calling this, navigation will fall back to full page reloads.
    */
   stop() {
-    document.removeEventListener("click", this.handleClick);
+    if (!this.started) {
+      return;
+    }
+    this.cancelNavigationTransaction();
+    document.removeEventListener("mouseover", this.handleHoverIntent, true);
+    document.removeEventListener("pointerover", this.handleHoverIntent, true);
+    document.removeEventListener("mousemove", this.handleHoverIntent, true);
+    document.removeEventListener("pointermove", this.handleHoverIntent, true);
+    document.removeEventListener("pointerdown", this.handlePointerDown, true);
+    document.removeEventListener("click", this.handleClick, true);
     window.removeEventListener("popstate", this.handlePopState);
     this.prefetchManager?.stop();
-    const windowWithHmr = window;
-    windowWithHmr.__ecopages_reload_current_page__ = void 0;
+    this.unregisterNavigationRuntime?.();
+    this.unregisterNavigationRuntime = null;
+    this.started = false;
+    this.pendingHoverNavigation = null;
+    this.pendingPointerNavigation = null;
+    this.queuedNavigationHref = null;
+    const win = window;
+    if (win[ACTIVE_ROUTER_KEY] === this) {
+      delete win[ACTIVE_ROUTER_KEY];
+    }
   }
   /**
    * Programmatic navigation.
@@ -88,24 +308,63 @@ class EcoRouter {
    * Uses `event.composedPath()` to correctly detect clicks on anchors inside
    * Shadow DOM boundaries (Web Components).
    */
+  handlePointerDown(event) {
+    const link = this.getLinkFromEvent(event);
+    if (!link) {
+      this.pendingPointerNavigation = null;
+      return;
+    }
+    const href = this.canInterceptLink(event, link);
+    this.pendingPointerNavigation = href ? {
+      href,
+      timestamp: performance.now()
+    } : null;
+    if (href && this.pendingNavigations > 0) {
+      this.queuedNavigationHref = href;
+    }
+  }
+  handleHoverIntent(event) {
+    const link = this.getLinkFromEvent(event);
+    if (!link) {
+      return;
+    }
+    const href = this.canInterceptLink(event, link);
+    if (!href) {
+      return;
+    }
+    this.pendingHoverNavigation = {
+      href,
+      timestamp: performance.now()
+    };
+    if (this.pendingNavigations > 0) {
+      this.queuedNavigationHref = href;
+    }
+  }
   handleClick(event) {
-    const link = event.composedPath().find(
-      (el) => el instanceof HTMLAnchorElement && el.matches(this.options.linkSelector)
-    );
-    if (!link) return;
-    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
-    if (event.button !== 0) return;
-    const target = link.getAttribute("target");
-    if (target && target !== "_self") return;
-    if (link.hasAttribute(this.options.reloadAttribute)) return;
-    if (link.hasAttribute("download")) return;
-    const href = link.getAttribute("href");
+    const navigationRuntime = getEcoNavigationRuntime(window);
+    const link = this.getLinkFromEvent(event);
+    const href = link ? this.canInterceptLink(event, link) : this.getRecoveredPointerHref() ?? this.getRecoveredHoverHref();
+    this.pendingPointerNavigation = null;
+    this.pendingHoverNavigation = null;
     if (!href) return;
-    if (href.startsWith("#")) return;
-    if (href.startsWith("javascript:")) return;
+    this.queuedNavigationHref = null;
+    if (this.isAnotherNavigationRuntimeActive()) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      void navigationRuntime.requestNavigation({
+        href,
+        direction: "forward",
+        source: "browser-router"
+      });
+      return;
+    }
     const url = new URL(href, window.location.origin);
-    if (!this.isSameOrigin(url)) return;
     event.preventDefault();
+    if (this.pendingNavigations > 0) {
+      this.queuedNavigationHref = href;
+      this.cancelNavigationTransaction();
+      return;
+    }
     this.performNavigation(url, "forward");
   }
   /**
@@ -113,6 +372,7 @@ class EcoRouter {
    * Triggered by the History API's popstate event.
    */
   handlePopState(_event) {
+    if (this.isAnotherNavigationRuntimeActive()) return;
     const url = new URL(window.location.href);
     this.performNavigation(url, "back");
   }
@@ -123,6 +383,17 @@ class EcoRouter {
   isSameOrigin(url) {
     return url.origin === window.location.origin;
   }
+  cancelNavigationTransaction() {
+    getEcoNavigationRuntime(window).cancelCurrentNavigationTransaction();
+  }
+  beginNavigationTransaction() {
+    const transaction = getEcoNavigationRuntime(window).beginNavigationTransaction();
+    return {
+      isStaleNavigation: () => !transaction.isCurrent(),
+      signal: transaction.signal,
+      complete: () => transaction.complete()
+    };
+  }
   /**
    * Executes the core navigation flow.
    *
@@ -142,64 +413,45 @@ class EcoRouter {
    * @param direction - Navigation direction ('forward', 'back', or 'replace')
    */
   async performNavigation(url, direction) {
-    const previousUrl = new URL(window.location.href);
-    this.abortController?.abort();
-    this.abortController = new AbortController();
+    this.pendingNavigations++;
+    const { isStaleNavigation, signal, complete } = this.beginNavigationTransaction();
+    let queuedNavigationHref = null;
     try {
-      const html = await this.fetchPage(url, this.abortController.signal);
+      const html = await this.fetchPage(url, signal);
+      if (isStaleNavigation()) return;
       const newDocument = this.domSwapper.parseHTML(html, url);
-      let shouldReload = false;
-      const beforeSwapEvent = {
-        url,
-        direction,
-        newDocument,
-        reload: () => {
-          shouldReload = true;
-        }
-      };
-      document.dispatchEvent(new CustomEvent("eco:before-swap", { detail: beforeSwapEvent }));
-      if (shouldReload) {
-        window.location.href = url.href;
-        return;
-      }
-      if (this.options.updateHistory && direction === "forward") {
-        window.history.pushState({}, "", url.href);
-      } else if (direction === "replace") {
-        window.history.replaceState({}, "", url.href);
-      }
-      const useViewTransitions = this.options.viewTransitions;
-      await this.domSwapper.preloadStylesheets(newDocument);
-      if (useViewTransitions) {
-        await this.viewTransitionManager.transition(() => {
-          this.domSwapper.morphHead(newDocument);
-          this.domSwapper.morphBody(newDocument);
-          this.scrollManager.handleScroll(url, previousUrl);
-        });
-      } else {
-        this.domSwapper.morphHead(newDocument);
-        this.domSwapper.replaceBody(newDocument);
-        this.scrollManager.handleScroll(url, previousUrl);
-      }
-      const afterSwapEvent = {
-        url,
-        direction
-      };
-      document.dispatchEvent(new CustomEvent("eco:after-swap", { detail: afterSwapEvent }));
-      this.prefetchManager?.observeNewLinks();
-      this.prefetchManager?.cacheVisitedPage(url.href, html);
-      requestAnimationFrame(() => {
-        document.dispatchEvent(
-          new CustomEvent("eco:page-load", {
-            detail: { url, direction }
-          })
-        );
+      if (isStaleNavigation()) return;
+      await this.commitDocumentNavigation(url, direction, newDocument, {
+        html,
+        isStaleNavigation
       });
     } catch (error) {
+      if (isStaleNavigation()) return;
       if (error instanceof Error && error.name === "AbortError") {
         return;
       }
       console.error("[ecopages] Navigation failed:", error);
       window.location.href = url.href;
+    } finally {
+      complete();
+      this.pendingNavigations--;
+      const navigationRuntime = getEcoNavigationRuntime(window);
+      if (!navigationRuntime.hasPendingNavigationTransaction()) {
+        queuedNavigationHref = this.queuedNavigationHref;
+        this.queuedNavigationHref = null;
+      }
+      if (queuedNavigationHref && queuedNavigationHref !== window.location.pathname + window.location.search) {
+        const ownerState = navigationRuntime.getOwnerState();
+        if (ownerState.owner !== "none" && ownerState.owner !== "browser-router" && ownerState.canHandleSpaNavigation) {
+          void navigationRuntime.requestNavigation({
+            href: queuedNavigationHref,
+            direction: "forward",
+            source: "browser-router"
+          });
+        } else {
+          void this.performNavigation(new URL(queuedNavigationHref, window.location.origin), "forward");
+        }
+      }
     }
   }
   /**
@@ -227,8 +479,15 @@ class EcoRouter {
     return response.text();
   }
 }
+const ACTIVE_ROUTER_KEY = "__ecopages_browser_router__";
 function createRouter(options) {
+  const win = window;
+  const existingRouter = win[ACTIVE_ROUTER_KEY];
+  if (existingRouter) {
+    return existingRouter;
+  }
   const router = new EcoRouter(options);
+  win[ACTIVE_ROUTER_KEY] = router;
   router.start();
   return router;
 }

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

@@ -12,6 +12,9 @@
  */
 export declare class DomSwapper {
     private persistAttribute;
+    private pendingHeadScripts;
+    private pendingRerunScripts;
+    private rerunNonce;
     constructor(persistAttribute: string);
     /**
      * Parses HTML string into a Document, injecting a temporary base tag for URL resolution.
@@ -38,12 +41,46 @@ export declare class DomSwapper {
      * - Injects new scripts from the incoming page that are absent from the current head
      */
     morphHead(newDocument: Document): void;
+    /**
+     * 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;
+    /**
+     * Returns whether pending rerun scripts require a full body replacement
+     * instead of morphing, so DOM-dependent bootstraps bind against fresh markup.
+     */
+    shouldReplaceBodyForRerunScripts(): boolean;
     /**
      * Detects custom elements without shadow DOM (light-DOM custom elements).
      * These need full replacement rather than morphing, because morphdom would
      * strip JS-generated content from their light DOM children.
      */
     private isLightDomCustomElement;
+    /**
+     * Queues a custom element for deferred replacement instead of replacing it
+     * inline during the morphdom walk.
+     *
+     * Replacing elements during morphdom traversal mutates the live DOM tree,
+     * which can cause morphdom to skip siblings or process stale nodes.
+     * Deferring the replacement until after morphdom finishes avoids this.
+     *
+     * @returns Always `false` to tell morphdom to skip updating this element.
+     */
+    private replaceCustomElement;
+    private materializeCustomElement;
+    /**
+     * Replaces all deferred custom elements after morphdom has finished traversing.
+     *
+     * Each element is recreated via `document.createElement` so the browser fires
+     * the full custom element lifecycle (`disconnectedCallback` on the old instance,
+     * `connectedCallback` on the new one). Elements that were already removed during
+     * the morph pass are skipped via the `isConnected` guard.
+     */
+    private flushDeferredCustomElementReplacements;
     /**
      * Morphs document body using morphdom.
      * Preserves persisted elements and hydrated custom elements.
@@ -57,6 +94,71 @@ export declare class DomSwapper {
      * Use when View Transitions are disabled.
      */
     replaceBody(newDocument: Document): void;
+    /**
+     * Collects all `data-eco-rerun` scripts from the incoming document.
+     *
+     * These scripts are re-executed after each navigation so their side-effects
+     * (event listeners, DOM bootstraps) bind against the new page content.
+     */
+    private collectRerunScripts;
+    /**
+     * Removes head scripts that are no longer present in the incoming document.
+     *
+     * Persisted scripts and executable inline scripts with stable identifiers
+     * are kept to avoid breaking long-lived runtime state.
+     */
+    private removeStaleHeadScripts;
+    /**
+     * Determines whether an inline head script should survive navigation.
+     *
+     * Only identified (`data-eco-script-id` or `id`), executable inline scripts
+     * are persisted. External scripts and rerun scripts are never persisted here
+     * because they have their own lifecycle management.
+     */
+    private shouldPersistExecutableInlineHeadScript;
+    /**
+     * Returns whether a script is non-executable (e.g. `type="application/json"`).
+     *
+     * Non-executable scripts are data carriers (JSON-LD, page data) that can be
+     * safely replaced without side-effects, unlike executable scripts that would
+     * re-run their bootstrap logic.
+     */
+    private isNonExecutableHeadScript;
+    /**
+     * Compares two head scripts for structural equality (key, content, attributes).
+     *
+     * Used to skip replacing non-executable data scripts when their content
+     * has not changed between navigations.
+     */
+    private areHeadScriptsEquivalent;
+    /**
+     * Derives a stable identity key for a head script.
+     *
+     * Priority: `data-eco-script-id` / `id` > `src` > trimmed inline content.
+     * Returns `null` for empty anonymous inline scripts that cannot be tracked.
+     */
+    private getHeadScriptKey;
+    /**
+     * Finds an existing head script that matches the given script's identity key.
+     */
+    private findExistingHeadScript;
+    /**
+     * Finds an existing rerun script in the given root by `data-eco-script-id` or
+     * by matching `src` and `textContent`.
+     */
+    private findExistingRerunScript;
+    /**
+     * Returns whether a rerun script is an external ES module (`type="module"` with `src`).
+     *
+     * Module scripts are cached by URL, so re-execution requires cache-busting
+     * via a query parameter nonce.
+     */
+    private isExternalModuleRerunScript;
+    /**
+     * Appends a nonce query parameter to a script URL to bust the browser's
+     * module cache and force re-execution on navigation.
+     */
+    private createRerunScriptUrl;
     /**
      * Manually attaches declarative shadow DOM templates.
      * Browsers only process `<template shadowrootmode>` during initial parse.