@ecopages/browser-router 0.2.0-alpha.9 → 0.2.1-beta.0

package/README.md

@@ -24,7 +24,7 @@ This package is designed for MPA-style rendering where the server returns full H
 ## Installation
 
 ```bash
-bunx jsr add @ecopages/browser-router
+bun add @ecopages/browser-router
 ```
 
 ## Usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/browser-router",
-  "version": "0.2.0-alpha.9",
+  "version": "0.2.1-beta.0",
   "description": "Client-side router for Ecopages with view transitions support",
   "keywords": [
     "ecopages",
@@ -35,7 +35,7 @@
     "morphdom": "^2.7.8"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.9"
+    "@ecopages/core": "0.2.1-beta.0"
   },
   "types": "./src/index.d.ts"
 }

package/src/client/eco-router.js

@@ -56,6 +56,9 @@ class EcoRouter {
     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() {

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

@@ -49,6 +49,10 @@ export declare class DomSwapper {
      * 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).
@@ -56,7 +60,27 @@ export declare class DomSwapper {
      * 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.
@@ -70,15 +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;
+    private getRegisteredRerunScript;
+    /**
+     * 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.

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

@@ -7,6 +7,12 @@ function isPersisted(element, persistAttribute) {
 function isHydratedCustomElement(element) {
   return element.localName.includes("-") && element.shadowRoot !== null;
 }
+function getBodyMorphKey(element, persistAttribute) {
+  if (!(element instanceof Element)) {
+    return void 0;
+  }
+  return element.getAttribute(persistAttribute) || element.getAttribute(DEFAULT_PERSIST_ATTR) || void 0;
+}
 class DomSwapper {
   persistAttribute;
   pendingHeadScripts = [];
@@ -180,8 +186,9 @@ class DomSwapper {
     this.pendingHeadScripts = [];
     for (const script of this.pendingRerunScripts) {
       const targetParent = script.parent === "body" ? document.body : document.head;
+      const registeredRerun = this.getRegisteredRerunScript(script.scriptId);
       const replacement = document.createElement("script");
-      const shouldBustModuleSrc = this.isExternalModuleRerunScript(script);
+      const shouldBustModuleSrc = this.isExternalModuleRerunScript(script) && !registeredRerun;
       for (const [name, value] of script.attributes) {
         if (name === "data-eco-rerun") {
           continue;
@@ -195,6 +202,13 @@ class DomSwapper {
       }
       replacement.textContent = script.textContent;
       const existingScript = this.findExistingRerunScript(targetParent, script);
+      if (registeredRerun) {
+        if (!existingScript) {
+          targetParent.appendChild(replacement);
+        }
+        registeredRerun();
+        continue;
+      }
       if (existingScript) {
         existingScript.replaceWith(replacement);
         continue;
@@ -203,6 +217,10 @@ class DomSwapper {
     }
     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;
   }
@@ -214,15 +232,43 @@ class DomSwapper {
   isLightDomCustomElement(element) {
     return element.localName.includes("-") && element.shadowRoot === null;
   }
-  replaceCustomElement(fromEl, toEl) {
-    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);
+  /**
+   * 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.cloneNode(true) });
     return false;
   }
+  materializeCustomElement(element) {
+    const materializedElement = document.createElement(element.localName);
+    for (const attr of element.attributes) {
+      materializedElement.setAttribute(attr.name, attr.value);
+    }
+    materializedElement.innerHTML = element.innerHTML;
+    return materializedElement;
+  }
+  /**
+   * 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 = this.materializeCustomElement(to);
+      from.replaceWith(newEl);
+    }
+  }
   /**
    * Morphs document body using morphdom.
    * Preserves persisted elements and hydrated custom elements.
@@ -231,16 +277,24 @@ class DomSwapper {
    */
   morphBody(newDocument) {
     const persistAttr = this.persistAttribute;
+    const deferredReplacements = [];
     morphdom(document.body, newDocument.body, {
+      getNodeKey: (node) => getBodyMorphKey(node, persistAttr),
+      onBeforeNodeAdded: (node) => {
+        if (node instanceof Element && this.isLightDomCustomElement(node)) {
+          return this.materializeCustomElement(node);
+        }
+        return node;
+      },
       onBeforeElUpdated: (fromEl, toEl) => {
         if (isPersisted(fromEl, persistAttr)) {
           return false;
         }
         if (isHydratedCustomElement(fromEl)) {
-          return this.replaceCustomElement(fromEl, toEl);
+          return this.replaceCustomElement(fromEl, toEl, deferredReplacements);
         }
         if (this.isLightDomCustomElement(fromEl)) {
-          return this.replaceCustomElement(fromEl, toEl);
+          return this.replaceCustomElement(fromEl, toEl, deferredReplacements);
         }
         if (fromEl.isEqualNode(toEl)) {
           return false;
@@ -248,6 +302,7 @@ class DomSwapper {
         return true;
       }
     });
+    this.flushDeferredCustomElementReplacements(deferredReplacements);
     this.processDeclarativeShadowDOM(document.body);
   }
   /**
@@ -273,9 +328,15 @@ 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",
@@ -285,6 +346,12 @@ class DomSwapper {
       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)
@@ -294,12 +361,22 @@ class DomSwapper {
       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) {
@@ -313,6 +390,13 @@ class DomSwapper {
     }
     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) {
@@ -326,6 +410,12 @@ class DomSwapper {
       "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;
@@ -345,6 +435,12 @@ class DomSwapper {
       ([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) {
@@ -357,6 +453,9 @@ class DomSwapper {
     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) {
@@ -366,6 +465,10 @@ class DomSwapper {
       (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) {
@@ -375,12 +478,29 @@ class DomSwapper {
       (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");
   }
+  getRegisteredRerunScript(scriptId) {
+    if (!scriptId) {
+      return null;
+    }
+    const runtimeWindow = window;
+    return runtimeWindow.__ECO_PAGES__?.rerunScripts?.[scriptId] ?? null;
+  }
+  /**
+   * 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));

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

@@ -14,6 +14,7 @@ export interface PrefetchOptions {
 export declare class PrefetchManager {
     private options;
     private prefetched;
+    private prefetchedStylesheets;
     private htmlCache;
     private observer;
     private hoverTimeouts;
@@ -159,12 +160,14 @@ export declare class PrefetchManager {
     /**
      * Prefetches stylesheets discovered in HTML content.
      *
-     * Parses the HTML to find stylesheet links, then creates preload hints
-     * for stylesheets not already present in the current document. This ensures
-     * styles are cached before navigation to prevent FOUC.
+     * Parses the HTML to find stylesheet links, then warms the HTTP cache for
+     * stylesheets not already present in the current document. This keeps future
+     * navigation CSS warm without injecting `preload` hints that browsers expect
+     * the current page to consume immediately.
      *
      * @param html - The raw HTML string to parse
      * @param url - The base URL for resolving relative stylesheet paths
      */
     private prefetchStylesheets;
+    private prefetchStylesheet;
 }

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

@@ -8,6 +8,7 @@ const DEFAULT_PREFETCH_OPTIONS = {
 class PrefetchManager {
   options;
   prefetched = /* @__PURE__ */ new Set();
+  prefetchedStylesheets = /* @__PURE__ */ new Set();
   htmlCache = /* @__PURE__ */ new Map();
   observer = null;
   hoverTimeouts = /* @__PURE__ */ new Map();
@@ -346,9 +347,10 @@ class PrefetchManager {
   /**
    * Prefetches stylesheets discovered in HTML content.
    *
-   * Parses the HTML to find stylesheet links, then creates preload hints
-   * for stylesheets not already present in the current document. This ensures
-   * styles are cached before navigation to prevent FOUC.
+   * Parses the HTML to find stylesheet links, then warms the HTTP cache for
+   * stylesheets not already present in the current document. This keeps future
+   * navigation CSS warm without injecting `preload` hints that browsers expect
+   * the current page to consume immediately.
    *
    * @param html - The raw HTML string to parse
    * @param url - The base URL for resolving relative stylesheet paths
@@ -358,20 +360,28 @@ class PrefetchManager {
     const doc = parser.parseFromString(`<base href="${url.href}">${html}`, "text/html");
     const existingHrefs = /* @__PURE__ */ new Set([
       ...Array.from(document.querySelectorAll('link[rel="stylesheet"]')).map((l) => l.href),
-      ...Array.from(document.querySelectorAll('link[rel="preload"][as="style"]')).map(
-        (l) => l.href
-      )
+      ...this.prefetchedStylesheets
     ]);
     const newStylesheets = doc.querySelectorAll('link[rel="stylesheet"]');
+    const stylesheetFetches = [];
     for (const link of newStylesheets) {
       if (!existingHrefs.has(link.href)) {
-        const preloadLink = document.createElement("link");
-        preloadLink.rel = "preload";
-        preloadLink.as = "style";
-        preloadLink.href = link.href;
-        document.head.appendChild(preloadLink);
+        existingHrefs.add(link.href);
+        this.prefetchedStylesheets.add(link.href);
+        stylesheetFetches.push(this.prefetchStylesheet(link.href));
       }
     }
+    await Promise.allSettled(stylesheetFetches);
+  }
+  async prefetchStylesheet(href) {
+    try {
+      await fetch(href, {
+        credentials: "same-origin",
+        priority: "low"
+      });
+    } catch {
+      this.prefetchedStylesheets.delete(href);
+    }
   }
 }
 export {

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

@@ -32,7 +32,18 @@ class ViewTransitionManager {
       await callback();
       applyViewTransitionNames();
     });
-    void 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;

package/CHANGELOG.md

@@ -1,31 +0,0 @@
-# Changelog
-
-All notable changes to `@ecopages/browser-router` are documented here.
-
-> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
-
-## [UNRELEASED] — TBD
-
-### Features
-
-- Added cross-router navigation handoff and document adoption hooks so browser-router can exchange control with other runtimes without forcing a reload.
-- Improved head swaps to execute newly introduced scripts and preserve light-DOM custom elements during page transitions.
-- Added `documentElementAttributesToSync` so apps can explicitly control which root `<html>` attributes browser-router synchronizes during navigation.
-- Added public document sync helpers so advanced setups can reuse browser-router's root `<html>` attribute synchronization logic without overriding the router pipeline.
-
-### Bug Fixes
-
-- Fixed stale delegated navigations and rapid-click races so only the latest browser-router navigation can commit a swap.
-- Re-executed `data-eco-rerun` scripts after body replacement and forced fresh module URLs for external rerun scripts so page bootstraps rebind correctly on every navigation.
-- Synced rendered document ownership markers and live `<html>` attributes during swaps so mixed browser-router and React-router pages preserve the correct hydration owner.
-- Preserved client-managed `<html>` state such as theme classes and data attributes while still syncing router-owned document metadata during swaps.
-- Prevented duplicate head-script execution, duplicate `/_hmr_runtime.js` injection, and listener accumulation across repeated navigations.
-- Reset hydrated custom elements from incoming HTML and ignored superseded navigation fetch failures so cross-runtime handoffs no longer leave blank or mixed DOM state behind.
-
-### Refactoring
-
-- Routed handoff and current-page reload behavior through the shared navigation coordinator.
-
-### Documentation
-
-- Updated the README examples for the current router API.

package/src/client/document-element-sync.ts

@@ -1,48 +0,0 @@
-/**
- * Helpers for synchronizing selected root `<html>` attributes during client-side navigation.
- * @module
- */
-
-import { DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC } from './types.ts';
-
-/**
- * Default root `<html>` attributes that browser-router treats as document-owned.
- *
- * These attributes are synchronized from the incoming document during navigation.
- * Other root attributes are preserved unless explicitly included.
- */
-export const defaultDocumentElementAttributesToSync = DEFAULT_DOCUMENT_ELEMENT_ATTRIBUTES_TO_SYNC;
-
-/**
- * Synchronizes a selected set of root `<html>` attributes from an incoming document
- * onto the current live document.
- *
- * Attributes listed here are treated as document-owned metadata. Attributes not
- * listed remain untouched on the live document so client-managed state can survive
- * across navigation swaps.
- *
- * @param currentDocument - The live document being updated
- * @param newDocument - The parsed incoming document for the next page
- * @param attributes - Root `<html>` attributes to synchronize
- */
-export function syncDocumentElementAttributes(
-	currentDocument: Document,
-	newDocument: Document,
-	attributes: readonly string[],
-): void {
-	const currentHtml = currentDocument.documentElement;
-	const nextHtml = newDocument.documentElement;
-
-	for (const attributeName of attributes) {
-		const nextValue = nextHtml.getAttribute(attributeName);
-
-		if (nextValue === null) {
-			currentHtml.removeAttribute(attributeName);
-			continue;
-		}
-
-		if (currentHtml.getAttribute(attributeName) !== nextValue) {
-			currentHtml.setAttribute(attributeName, nextValue);
-		}
-	}
-}