@ecopages/browser-router 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/client/services/dom-swapper.js

@@ -1,5 +1,6 @@
 import morphdom from "morphdom";
 const DEFAULT_PERSIST_ATTR = "data-eco-persist";
+const RERUN_SRC_ATTR = "data-eco-rerun-src";
 function isPersisted(element, persistAttribute) {
   return element.hasAttribute(persistAttribute) || element.hasAttribute(DEFAULT_PERSIST_ATTR);
 }
@@ -8,6 +9,9 @@ function isHydratedCustomElement(element) {
 }
 class DomSwapper {
   persistAttribute;
+  pendingHeadScripts = [];
+  pendingRerunScripts = [];
+  rerunNonce = 0;
   constructor(persistAttribute) {
     this.persistAttribute = persistAttribute;
   }
@@ -78,6 +82,9 @@ class DomSwapper {
    * - Injects new scripts from the incoming page that are absent from the current head
    */
   morphHead(newDocument) {
+    this.pendingHeadScripts = [];
+    this.pendingRerunScripts = this.collectRerunScripts(newDocument);
+    this.removeStaleHeadScripts(newDocument);
     const newTitle = newDocument.head.querySelector("title");
     if (newTitle && document.title !== newTitle.textContent) {
       document.title = newTitle.textContent || "";
@@ -97,25 +104,6 @@ class DomSwapper {
         document.head.appendChild(newMeta.cloneNode(true));
       }
     }
-    const existingScriptIds = new Set(
-      Array.from(document.head.querySelectorAll("script[data-eco-script-id]")).map(
-        (s) => s.getAttribute("data-eco-script-id")
-      )
-    );
-    const rerunScripts = newDocument.head.querySelectorAll("script[data-eco-rerun]");
-    for (const script of rerunScripts) {
-      const scriptId = script.getAttribute("data-eco-script-id");
-      if (scriptId && !existingScriptIds.has(scriptId)) {
-        const newScript = document.createElement("script");
-        for (const attr of script.attributes) {
-          if (attr.name !== "data-eco-rerun") {
-            newScript.setAttribute(attr.name, attr.value);
-          }
-        }
-        newScript.textContent = script.textContent;
-        document.head.appendChild(newScript);
-      }
-    }
     const existingScriptSrcs = new Set(
       Array.from(document.head.querySelectorAll("script[src]")).map((s) => s.getAttribute("src"))
     );
@@ -126,27 +114,102 @@ class DomSwapper {
     for (const script of allNewHeadScripts) {
       if (script.hasAttribute("data-eco-rerun")) continue;
       const src = script.getAttribute("src");
+      const scriptId = script.getAttribute("data-eco-script-id") || script.getAttribute("id");
+      const existingScript = this.findExistingHeadScript(script);
+      if (scriptId && existingScript) {
+        if (!this.isNonExecutableHeadScript(script)) {
+          continue;
+        }
+        if (this.areHeadScriptsEquivalent(script, existingScript)) {
+          continue;
+        }
+        this.pendingHeadScripts.push({
+          attributes: Array.from(script.attributes).map((attr) => [attr.name, attr.value]),
+          textContent: script.textContent ?? "",
+          src,
+          scriptId,
+          replaceExisting: true
+        });
+        continue;
+      }
       if (src) {
         if (existingScriptSrcs.has(src)) continue;
-        const newScript = document.createElement("script");
-        for (const attr of script.attributes) {
-          newScript.setAttribute(attr.name, attr.value);
-        }
-        document.head.appendChild(newScript);
+        this.pendingHeadScripts.push({
+          attributes: Array.from(script.attributes).map((attr) => [attr.name, attr.value]),
+          textContent: script.textContent ?? "",
+          src,
+          scriptId,
+          replaceExisting: false
+        });
         existingScriptSrcs.add(src);
       } else {
         const content = (script.textContent ?? "").trim();
         if (!content || existingInlineContents.has(content)) continue;
-        const newScript = document.createElement("script");
-        for (const attr of script.attributes) {
-          newScript.setAttribute(attr.name, attr.value);
-        }
-        newScript.textContent = script.textContent;
-        document.head.appendChild(newScript);
+        this.pendingHeadScripts.push({
+          attributes: Array.from(script.attributes).map((attr) => [attr.name, attr.value]),
+          textContent: script.textContent ?? "",
+          src: null,
+          scriptId,
+          replaceExisting: false
+        });
         existingInlineContents.add(content);
       }
     }
   }
+  /**
+   * 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() {
+    for (const script of this.pendingHeadScripts) {
+      const replacement = document.createElement("script");
+      for (const [name, value] of script.attributes) {
+        replacement.setAttribute(name, value);
+      }
+      replacement.textContent = script.textContent;
+      const existingScript = this.findExistingHeadScript(script);
+      if (script.replaceExisting && existingScript) {
+        existingScript.replaceWith(replacement);
+        continue;
+      }
+      document.head.appendChild(replacement);
+    }
+    this.pendingHeadScripts = [];
+    for (const script of this.pendingRerunScripts) {
+      const targetParent = script.parent === "body" ? document.body : document.head;
+      const replacement = document.createElement("script");
+      const shouldBustModuleSrc = this.isExternalModuleRerunScript(script);
+      for (const [name, value] of script.attributes) {
+        if (name === "data-eco-rerun") {
+          continue;
+        }
+        if (name === "src" && shouldBustModuleSrc) {
+          replacement.setAttribute(RERUN_SRC_ATTR, value);
+          replacement.setAttribute("src", this.createRerunScriptUrl(value));
+          continue;
+        }
+        replacement.setAttribute(name, value);
+      }
+      replacement.textContent = script.textContent;
+      const existingScript = this.findExistingRerunScript(targetParent, script);
+      if (existingScript) {
+        existingScript.replaceWith(replacement);
+        continue;
+      }
+      targetParent.appendChild(replacement);
+    }
+    this.pendingRerunScripts = [];
+  }
+  /**
+   * Returns whether pending rerun scripts require a full body replacement
+   * instead of morphing, so DOM-dependent bootstraps bind against fresh markup.
+   */
+  shouldReplaceBodyForRerunScripts() {
+    return this.pendingRerunScripts.length > 0;
+  }
   /**
    * Detects custom elements without shadow DOM (light-DOM custom elements).
    * These need full replacement rather than morphing, because morphdom would
@@ -155,6 +218,39 @@ class DomSwapper {
   isLightDomCustomElement(element) {
     return element.localName.includes("-") && element.shadowRoot === null;
   }
+  /**
+   * 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.
+   */
+  replaceCustomElement(fromEl, toEl, deferred) {
+    deferred.push({ from: fromEl, to: toEl });
+    return false;
+  }
+  /**
+   * 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.
+   */
+  flushDeferredCustomElementReplacements(deferred) {
+    for (const { from, to } of deferred) {
+      if (!from.isConnected) continue;
+      const newEl = document.createElement(to.tagName);
+      for (const attr of to.attributes) {
+        newEl.setAttribute(attr.name, attr.value);
+      }
+      newEl.innerHTML = to.innerHTML;
+      from.replaceWith(newEl);
+    }
+  }
   /**
    * Morphs document body using morphdom.
    * Preserves persisted elements and hydrated custom elements.
@@ -163,22 +259,17 @@ class DomSwapper {
    */
   morphBody(newDocument) {
     const persistAttr = this.persistAttribute;
+    const deferredReplacements = [];
     morphdom(document.body, newDocument.body, {
       onBeforeElUpdated: (fromEl, toEl) => {
         if (isPersisted(fromEl, persistAttr)) {
           return false;
         }
         if (isHydratedCustomElement(fromEl)) {
-          return false;
+          return this.replaceCustomElement(fromEl, toEl, deferredReplacements);
         }
         if (this.isLightDomCustomElement(fromEl)) {
-          const newEl = document.createElement(toEl.tagName);
-          for (const attr of toEl.attributes) {
-            newEl.setAttribute(attr.name, attr.value);
-          }
-          newEl.innerHTML = toEl.innerHTML;
-          fromEl.replaceWith(newEl);
-          return false;
+          return this.replaceCustomElement(fromEl, toEl, deferredReplacements);
         }
         if (fromEl.isEqualNode(toEl)) {
           return false;
@@ -186,6 +277,7 @@ class DomSwapper {
         return true;
       }
     });
+    this.flushDeferredCustomElementReplacements(deferredReplacements);
     this.processDeclarativeShadowDOM(document.body);
   }
   /**
@@ -211,9 +303,177 @@ class DomSwapper {
         placeholder.replaceWith(oldEl);
       }
     }
-    document.body.replaceChildren(...newDocument.body.childNodes);
+    document.body.replaceChildren(...Array.from(newDocument.body.childNodes));
     this.processDeclarativeShadowDOM(document.body);
   }
+  /**
+   * 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.
+   */
+  collectRerunScripts(newDocument) {
+    return Array.from(newDocument.querySelectorAll("script[data-eco-rerun]")).map((script) => ({
+      parent: script.closest("body") ? "body" : "head",
+      attributes: Array.from(script.attributes).map((attr) => [attr.name, attr.value]),
+      textContent: script.textContent ?? "",
+      src: script.getAttribute("src"),
+      scriptId: script.getAttribute("data-eco-script-id")
+    }));
+  }
+  /**
+   * 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.
+   */
+  removeStaleHeadScripts(newDocument) {
+    const nextScriptKeys = new Set(
+      Array.from(newDocument.head.querySelectorAll("script")).map((script) => this.getHeadScriptKey(script)).filter((key) => key !== null)
+    );
+    for (const script of Array.from(document.head.querySelectorAll("script"))) {
+      const key = this.getHeadScriptKey(script);
+      if (!key || nextScriptKeys.has(key)) {
+        continue;
+      }
+      if (isPersisted(script, this.persistAttribute)) {
+        continue;
+      }
+      if (this.shouldPersistExecutableInlineHeadScript(script)) {
+        continue;
+      }
+      script.remove();
+    }
+  }
+  /**
+   * 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.
+   */
+  shouldPersistExecutableInlineHeadScript(script) {
+    const scriptId = script.getAttribute("data-eco-script-id") || script.getAttribute("id");
+    if (!scriptId) {
+      return false;
+    }
+    if (script.hasAttribute("data-eco-rerun")) {
+      return false;
+    }
+    if (script.getAttribute(RERUN_SRC_ATTR) || script.getAttribute("src")) {
+      return false;
+    }
+    return !this.isNonExecutableHeadScript(script);
+  }
+  /**
+   * 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.
+   */
+  isNonExecutableHeadScript(script) {
+    const type = (script.getAttribute("type") ?? "").trim().toLowerCase();
+    if (!type) {
+      return false;
+    }
+    return ![
+      "application/javascript",
+      "application/ecmascript",
+      "module",
+      "text/ecmascript",
+      "text/javascript"
+    ].includes(type);
+  }
+  /**
+   * 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.
+   */
+  areHeadScriptsEquivalent(nextScript, currentScript) {
+    if (this.getHeadScriptKey(nextScript) !== this.getHeadScriptKey(currentScript)) {
+      return false;
+    }
+    if ((nextScript.textContent ?? "") !== (currentScript.textContent ?? "")) {
+      return false;
+    }
+    const nextAttributes = Array.from(nextScript.attributes).map((attribute) => [attribute.name, attribute.value]);
+    const currentAttributes = Array.from(currentScript.attributes).map((attribute) => [
+      attribute.name,
+      attribute.value
+    ]);
+    if (nextAttributes.length !== currentAttributes.length) {
+      return false;
+    }
+    return nextAttributes.every(
+      ([name, value], index) => currentAttributes[index]?.[0] === name && currentAttributes[index]?.[1] === value
+    );
+  }
+  /**
+   * 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.
+   */
+  getHeadScriptKey(script) {
+    const scriptId = script instanceof HTMLScriptElement ? script.getAttribute("data-eco-script-id") || script.getAttribute("id") : script.scriptId;
+    if (scriptId) {
+      return `id:${scriptId}`;
+    }
+    const src = script instanceof HTMLScriptElement ? script.getAttribute(RERUN_SRC_ATTR) || script.getAttribute("src") : script.src;
+    if (src) {
+      return `src:${src}`;
+    }
+    const textContent = (script.textContent ?? "").trim();
+    return textContent ? `inline:${textContent}` : null;
+  }
+  /**
+   * Finds an existing head script that matches the given script's identity key.
+   */
+  findExistingHeadScript(script) {
+    const scriptKey = this.getHeadScriptKey(script);
+    if (!scriptKey) {
+      return null;
+    }
+    return Array.from(document.head.querySelectorAll("script")).find(
+      (candidate) => this.getHeadScriptKey(candidate) === scriptKey
+    ) ?? null;
+  }
+  /**
+   * Finds an existing rerun script in the given root by `data-eco-script-id` or
+   * by matching `src` and `textContent`.
+   */
+  findExistingRerunScript(root, script) {
+    const scripts = Array.from(root.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;
+  }
+  /**
+   * 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.
+   */
+  isExternalModuleRerunScript(script) {
+    if (!script.src) {
+      return false;
+    }
+    return script.attributes.some(([name, value]) => name === "type" && value === "module");
+  }
+  /**
+   * Appends a nonce query parameter to a script URL to bust the browser's
+   * module cache and force re-execution on navigation.
+   */
+  createRerunScriptUrl(src) {
+    const url = new URL(src, document.baseURI);
+    url.searchParams.set("__eco_rerun", String(++this.rerunNonce));
+    return url.toString();
+  }
   /**
    * Manually attaches declarative shadow DOM templates.
    * Browsers only process `<template shadowrootmode>` during initial parse.

package/src/client/services/prefetch-manager.d.ts

@@ -52,6 +52,7 @@ export declare class PrefetchManager {
      * @returns The cached HTML string, or null if not cached
      */
     getCachedHtml(href: string): string | null;
+    invalidate(href: string): void;
     /**
      * Caches HTML content for a visited page and triggers background revalidation.
      *

package/src/client/services/prefetch-manager.js

@@ -89,6 +89,11 @@ class PrefetchManager {
     const url = new URL(href, window.location.origin);
     return this.htmlCache.get(url.href) ?? null;
   }
+  invalidate(href) {
+    const url = new URL(href, window.location.origin);
+    this.htmlCache.delete(url.href);
+    this.prefetched.delete(url.href);
+  }
   /**
    * Caches HTML content for a visited page and triggers background revalidation.
    *

package/src/client/services/view-transition-manager.d.ts

@@ -16,8 +16,14 @@ export declare class ViewTransitionManager {
     /**
      * Execute a callback with view transition if available and enabled.
      * Falls back to direct execution if not supported.
+     *
+     * Navigation correctness depends on the DOM update callback completing, not on
+     * the browser finishing the visual transition animation. Awaiting
+     * `finished` here can leave router transactions artificially in-flight and
+     * block later navigations during rapid repeated clicks, so the router waits
+     * for `updateCallbackDone` and lets the animation finish in the background.
      * @param callback - The DOM update callback to execute
-     * @returns Promise that resolves when the transition completes
+     * @returns Promise that resolves when the DOM update has committed
      */
     transition(callback: () => void | Promise<void>): Promise<void>;
 }

package/src/client/services/view-transition-manager.js

@@ -13,8 +13,14 @@ class ViewTransitionManager {
   /**
    * Execute a callback with view transition if available and enabled.
    * Falls back to direct execution if not supported.
+   *
+   * Navigation correctness depends on the DOM update callback completing, not on
+   * the browser finishing the visual transition animation. Awaiting
+   * `finished` here can leave router transactions artificially in-flight and
+   * block later navigations during rapid repeated clicks, so the router waits
+   * for `updateCallbackDone` and lets the animation finish in the background.
    * @param callback - The DOM update callback to execute
-   * @returns Promise that resolves when the transition completes
+   * @returns Promise that resolves when the DOM update has committed
    */
   async transition(callback) {
     if (!this.enabled || !this.isSupported()) {
@@ -26,11 +32,21 @@ class ViewTransitionManager {
       await callback();
       applyViewTransitionNames();
     });
-    try {
-      await transition.finished;
-    } finally {
+    void transition.ready.catch((error) => {
+      if (error instanceof Error && error.name === "AbortError") {
+        return;
+      }
+      console.error("[ecopages] View transition failed to start:", error);
+    });
+    void transition.finished.catch((error) => {
+      if (error instanceof Error && error.name === "AbortError") {
+        return;
+      }
+      console.error("[ecopages] View transition lifecycle failed:", error);
+    }).finally(() => {
       clearViewTransitionNames();
-    }
+    });
+    await transition.updateCallbackDone;
   }
 }
 export {

package/src/client/types.d.ts

@@ -36,6 +36,13 @@ export interface PrefetchConfig {
 export interface EcoRouterOptions {
     /** Selector for links to intercept. @default 'a[href]' */
     linkSelector?: string;
+    /**
+     * Document-level `<html>` attributes to sync from the incoming document during navigation.
+     * Attributes not listed here are preserved on the live document element so client-managed
+     * state such as theme classes or data attributes is not clobbered during swaps.
+     * @default ['lang', 'dir', 'data-eco-document-owner']
+     */
+    documentElementAttributesToSync?: string[];
     /** Attribute to mark elements for DOM persistence. @default 'data-eco-persist' */
     persistAttribute?: string;
     /** Attribute to force full page reload. @default 'data-eco-reload' */
@@ -67,6 +74,9 @@ export interface EcoRouterOptions {
      */
     prefetch?: PrefetchConfig | false;
 }
+export type BrowserRouterNavigateOptions = {
+    direction?: 'forward' | 'back' | 'replace';
+};
 /** Events emitted during the navigation lifecycle */
 export interface EcoNavigationEvent {
     url: URL;
@@ -80,5 +90,7 @@ export interface EcoBeforeSwapEvent extends EcoNavigationEvent {
 /** Event fired after the DOM swap completes */
 export interface EcoAfterSwapEvent extends EcoNavigationEvent {
 }
+/** Default document-level `<html>` attributes synchronized during navigation swaps. */
+export declare const DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC: string[];
 /** Default configuration options */
 export declare const DEFAULT_OPTIONS: Required<EcoRouterOptions>;

package/src/client/types.js

@@ -1,11 +1,14 @@
+import { ECO_DOCUMENT_OWNER_ATTRIBUTE } from "@ecopages/core/router/navigation-coordinator";
 const DEFAULT_PREFETCH_CONFIG = {
   strategy: "intent",
   delay: 65,
   noPrefetchAttribute: "data-eco-no-prefetch",
   respectDataSaver: true
 };
+const DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC = ["lang", "dir", ECO_DOCUMENT_OWNER_ATTRIBUTE];
 const DEFAULT_OPTIONS = {
   linkSelector: "a[href]",
+  documentElementAttributesToSync: DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC,
   persistAttribute: "data-eco-persist",
   reloadAttribute: "data-eco-reload",
   updateHistory: true,
@@ -15,5 +18,6 @@ const DEFAULT_OPTIONS = {
   prefetch: DEFAULT_PREFETCH_CONFIG
 };
 export {
+  DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC,
   DEFAULT_OPTIONS
 };

package/src/index.d.ts

@@ -4,6 +4,7 @@
  * @module
  */
 export type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent, EcoRouterEventMap, } from './types.js';
-export { DEFAULT_OPTIONS } from './types.js';
+export { DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC, DEFAULT_OPTIONS } from './types.js';
+export { defaultDocumentElementAttributesToSync, syncDocumentElementAttributes, } from './client/document-element-sync.js';
 export { EcoRouter, createRouter } from './client/eco-router.js';
 export { DomSwapper, ScrollManager, ViewTransitionManager } from './client/services/index.js';

package/src/index.js

@@ -1,11 +1,18 @@
-import { DEFAULT_OPTIONS } from "./types.js";
+import { DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC, DEFAULT_OPTIONS } from "./types.js";
+import {
+  defaultDocumentElementAttributesToSync,
+  syncDocumentElementAttributes
+} from "./client/document-element-sync.js";
 import { EcoRouter, createRouter } from "./client/eco-router.js";
 import { DomSwapper, ScrollManager, ViewTransitionManager } from "./client/services/index.js";
 export {
+  DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC,
   DEFAULT_OPTIONS,
   DomSwapper,
   EcoRouter,
   ScrollManager,
   ViewTransitionManager,
-  createRouter
+  createRouter,
+  defaultDocumentElementAttributesToSync,
+  syncDocumentElementAttributes
 };

package/src/types.d.ts

@@ -4,7 +4,7 @@
  */
 import type { EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './client/types';
 export type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './client/types';
-export { DEFAULT_OPTIONS } from './client/types';
+export { DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC, DEFAULT_OPTIONS } from './client/types';
 /**
  * Custom event map for navigation lifecycle
  */

package/src/types.js

@@ -1,4 +1,5 @@
-import { DEFAULT_OPTIONS } from "./client/types";
+import { DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC, DEFAULT_OPTIONS } from "./client/types";
 export {
+  DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC,
   DEFAULT_OPTIONS
 };