npm - @ecopages/browser-router - Versions diffs - 0.2.0-alpha.10 → 0.2.0-alpha.11 - Mend

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

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 (6) hide show

package/CHANGELOG.md +4 -10
package/package.json +2 -2
package/src/client/eco-router.js +3 -0
package/src/client/services/dom-swapper.d.ts +78 -0
package/src/client/services/dom-swapper.js +98 -10
package/src/client/services/view-transition-manager.js +12 -1

package/CHANGELOG.md CHANGED Viewed

@@ -8,19 +8,13 @@ All notable changes to `@ecopages/browser-router` are documented here.
 ### 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.
+- Added cross-router handoff hooks, configurable `<html>` attribute syncing, and public document sync helpers.
 ### 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.
+- Fixed navigation races, duplicate script injection, and stale cleanup during repeated page swaps.
+- Fixed mixed-runtime document ownership, script reruns, persisted head scripts, and client-managed `<html>` state during browser-router navigations.
+- Fixed skipped View Transition lifecycle aborts leaking as unhandled browser-router test errors.
 ### Refactoring

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/browser-router",
-  "version": "0.2.0-alpha.10",
+  "version": "0.2.0-alpha.11",
   "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.10"
+    "@ecopages/core": "0.2.0-alpha.11"
   },
   "types": "./src/index.d.ts"
 }

package/src/client/eco-router.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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,26 @@ 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;
+    /**
+     * 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 +93,70 @@ 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.

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

@@ -203,6 +203,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 +218,39 @@ 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 });
     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.
@@ -231,16 +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 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 +277,7 @@ class DomSwapper {
         return true;
       }
     });
+    this.flushDeferredCustomElementReplacements(deferredReplacements);
     this.processDeclarativeShadowDOM(document.body);
   }
   /**
@@ -273,9 +303,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 +321,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 +336,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 +365,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 +385,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 +410,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 +428,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 +440,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 +453,22 @@ 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");
   }
+  /**
+   * 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/view-transition-manager.js CHANGED Viewed

@@ -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;