npm - @ecopages/browser-router - Versions diffs - 0.2.0-alpha.1 - Mend

@ecopages/browser-router 0.2.0-alpha.1

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

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,25 @@
+# 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
+- **Light-DOM custom element support in `dom-swapper`** — `morphdom` morphing process now correctly handles light-DOM custom elements during page transitions (`fce8080c`).
+- **Improved `morphHead` script injection** — New scripts from the incoming page's `<head>` are now injected and executed correctly during client-side navigation, even when not marked with `data-eco-rerun` (`08e15e99`).
+- **Global injector lifecycle management** — Enhanced global injector with structured lifecycle hooks and tests for hydration script handling (`2ba35aa4`).
+### Bug Fixes
+- Published npm package metadata now includes validated declaration exports for generated dist entrypoints.
+### Refactoring
+- Removed unused `@types/morphdom` dev dependency (`ceb243d0`).
+### Documentation
+- README updated with new API usage examples.

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025-present Andrea Zanenghi
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,132 @@
+# @ecopages/browser-router
+Client-side navigation and view transitions for Ecopages. Intercepts same-origin link clicks to provide smooth page transitions without full page reloads.
+## Features
+- **Client-side navigation** - Intercepts `<a>` clicks for fast navigation
+- **Efficient DOM diffing** - Uses [morphdom](https://github.com/patrick-steele-idem/morphdom) to update only what changed, preserving scroll positions and internal state
+- **State persistence** - Elements with `data-eco-persist` are never recreated, preserving internal state
+- **View Transitions** - Optional integration with the View Transition API
+- **Lifecycle events** - Hook into navigation with `eco:before-swap`, `eco:after-swap`, `eco:page-load`
+## Compatibility
+This package works with MPA-style rendering (KitaJS, Lit, vanilla JS) where the server returns full HTML pages.
+**Not compatible with React/Preact** - These frameworks manage their own virtual DOM and component trees. Replacing the DOM breaks hydration, state, and event handlers. For React apps, use a framework-specific routing solution.
+Component-level islands are a narrower case: small interactive roots emitted by another integration (for example a React island inside an otherwise MPA-style page) can work with `@ecopages/browser-router`, because ownership stays scoped to the island root instead of the full document.
+## Installation
+```bash
+bunx jsr add @ecopages/browser-router
+```
+## Usage
+Create and start the router in a **global** client-side script (e.g., `src/layouts/base-layout.script.ts`).
+> **Important**: Ensure the router script is injected in a **consistent order** within the `<head>` across all pages. Inconsistent ordering (e.g. script between styles on one page but after on another) causes `morphdom` to reload styles, leading to a "Flash of Unstyled Content" (FOUC).
+```ts
+import { createRouter } from '@ecopages/browser-router/client';
+// Creates and starts the router with default options
+const router = createRouter();
+```
+With custom options:
+```ts
+import { createRouter } from '@ecopages/browser-router/client';
+const router = createRouter({
+	viewTransitions: true,
+	scrollBehavior: 'auto',
+});
+```
+## Configuration
+| Option             |              Type               |       Default        | Description                                    |
+| :----------------- | :-----------------------------: | :------------------: | :--------------------------------------------- |
+| `linkSelector`     |            `string`             |     `'a[href]'`      | Selector for links to intercept                |
+| `persistAttribute` |            `string`             | `'data-eco-persist'` | Attribute to mark elements for DOM persistence |
+| `reloadAttribute`  |            `string`             | `'data-eco-reload'`  | Attribute to force full page reload            |
+| `updateHistory`    |            `boolean`            |        `true`        | Whether to update browser history              |
+| `scrollBehavior`   | `'top' \| 'preserve' \| 'auto'` |       `'top'`        | Scroll behavior after navigation               |
+| `viewTransitions`  |            `boolean`            |       `false`        | Use View Transition API for animations         |
+| `smoothScroll`     |            `boolean`            |       `false`        | Use smooth scrolling during navigation         |
+## Persistence
+Mark elements to preserve across navigations. These elements are never recreated during navigation, morphdom skips them entirely, preserving their internal state (event listeners, web component state, form values, etc.):
+```html
+<!-- This counter keeps its state across all navigations -->
+<radiant-counter data-eco-persist="counter"></radiant-counter>
+```
+## Script Re-execution
+To force a script to re-execute on every navigation (e.g. analytics, hydration), add `data-eco-rerun` and `data-eco-script-id`:
+```html
+<script data-eco-rerun="true" data-eco-script-id="analytics">
+	// This runs on every navigation
+	trackPageview();
+</script>
+```
+### React islands with `@ecopages/browser-router`
+When `@ecopages/browser-router` is used in an MPA-style app that also renders component-level React islands:
+- island hydration scripts may need to run again after `eco:after-swap`
+- hydration bootstraps should carry stable `data-eco-script-id` metadata
+- `data-eco-rerun` allows those bootstraps to be re-executed safely during head reconciliation
+This note is specific to DOM-swapping navigation with `@ecopages/browser-router`. It does **not** apply to full React applications using [@ecopages/react-router](../react-router/README.md), where page routing and hydration are handled by the React router runtime itself.
+## Force Full Reload
+Use `data-eco-reload` to force a full page reload:
+```html
+<a href="/logout" data-eco-reload>Logout</a>
+```
+## Events
+Listen to navigation lifecycle events:
+```ts
+document.addEventListener('eco:before-swap', (e) => {
+	console.log('Navigating to:', e.detail.url);
+	// Call e.detail.reload() to abort and do full reload
+});
+document.addEventListener('eco:after-swap', (e) => {
+	console.log('Swapped to:', e.detail.url);
+});
+document.addEventListener('eco:page-load', (e) => {
+	console.log('Page loaded:', e.detail.url);
+});
+```
+## Programmatic Navigation
+```ts
+import { createRouter } from '@ecopages/browser-router/client';
+const router = createRouter();
+// Navigate with pushState
+await router.navigate('/new-page');
+// Navigate with replaceState
+await router.navigate('/new-page', { replace: true });
+```

package/package.json ADDED Viewed

@@ -0,0 +1,39 @@
+{
+  "name": "@ecopages/browser-router",
+  "version": "0.2.0-alpha.1",
+  "description": "Client-side router for Ecopages with view transitions support",
+  "keywords": [
+    "ecopages",
+    "router",
+    "browser-router",
+    "navigation",
+    "spa",
+    "view-transitions"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./client": {
+      "types": "./src/client/eco-router.d.ts",
+      "default": "./src/client/eco-router.js"
+    },
+    "./client.ts": {
+      "types": "./src/client/eco-router.d.ts",
+      "default": "./src/client/eco-router.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ecopages/ecopages.git",
+    "directory": "packages/browser-router"
+  },
+  "dependencies": {
+    "@ecopages/core": "0.2.0-alpha.1",
+    "morphdom": "^2.7.8"
+  },
+  "types": "./src/index.d.ts"
+}

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Initialization-should-create-router-instance-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Initialization-should-start-and-stop-without-errors-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Lifecycle-Events-should-dispatch-eco-before-swap--eco-after-swap--and-eco-page-load-events-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Lifecycle-Events-should-dispatch-eco-page-load-event-after-animation-frame-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Lifecycle-Events-should-provide-event-details-with-url-and-direction-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Custom-Link-Selector-should-work-with-data-attribute-selector-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Custom-Reload-Attribute-should-intercept-links-with-default-reload-attribute-when-custom-is-set-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Custom-link-selector-should-only-intercept-links-matching-custom-selector-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-External-Links--should-NOT-intercept--should-NOT-intercept-external-links-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Internal-Links-should-intercept-clicks-on-relative-path-links-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Internal-Links-should-intercept-clicks-on-same-origin-absolute-URLs-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Link-Attributes--should-NOT-intercept--should-NOT-intercept-links-with-download-attribute-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Link-Attributes--should-NOT-intercept--should-intercept-links-with-target---self--1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Modifier-keys-should-NOT-intercept-alt-click-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Modifier-keys-should-NOT-intercept-ctrl-click-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Modifier-keys-should-NOT-intercept-meta-click--cmd-on-Mac--1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Modifier-keys-should-NOT-intercept-middle-mouse-button-click-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Modifier-keys-should-NOT-intercept-right-mouse-button-click-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Modifier-keys-should-NOT-intercept-shift-click-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-NOT-intercept-external-links--different-origin--1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-NOT-intercept-hash-only-links-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-NOT-intercept-javascript--links-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-NOT-intercept-links-with-custom-reload-attribute-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-NOT-intercept-links-with-data-eco-reload-attribute-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-NOT-intercept-links-with-download-attribute-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-NOT-intercept-links-with-empty-href-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-NOT-intercept-links-with-target---blank--1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-NOT-intercept-links-with-target---parent--1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-NOT-intercept-links-without-href-attribute-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-intercept-internal-links-with-absolute-same-origin-paths-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-intercept-internal-links-with-relative-paths-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-Should-intercept-nested-elements-inside-links-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Link-Interception-should-NOT-intercept-external-links-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Navigation-Abort-should-abort-previous-navigation-when-new-one-starts-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Programmatic-Navigation-should-navigate-and-update-history-with-pushState-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.browser.ts/EcoRouter-Programmatic-Navigation-should-use-replaceState-when-replace-option-is-true-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.ts/EcoRouter-Error-Handling-should-fall-back-to-full-page-navigation-on-fetch-error-1.png ADDED Viewed

Binary file

package/src/client/__screenshots__/eco-router.test.ts/EcoRouter-Error-Handling-should-log-error-and-attempt-fallback-navigation-on-fetch-error-1.png ADDED Viewed

Binary file

package/src/client/eco-router.d.ts ADDED Viewed

@@ -0,0 +1,98 @@
+/**
+ * Client-side router for Ecopages with morphdom-based DOM diffing.
+ * @module eco-router
+ */
+import type { EcoRouterOptions } from './types.js';
+/**
+ * Intercepts same-origin link clicks and performs client-side navigation
+ * using morphdom for efficient DOM diffing. Supports View Transitions API.
+ */
+export declare class EcoRouter {
+    private options;
+    private abortController;
+    private domSwapper;
+    private scrollManager;
+    private viewTransitionManager;
+    private prefetchManager;
+    constructor(options?: EcoRouterOptions);
+    /**
+     * Starts the router and begins intercepting navigation.
+     *
+     * Attaches click handlers for links and popstate handlers for browser
+     * back/forward buttons. Also starts the prefetch manager if configured.
+     */
+    start(): void;
+    /**
+     * Stops the router and cleans up all event listeners.
+     * After calling this, navigation will fall back to full page reloads.
+     */
+    stop(): void;
+    /**
+     * Programmatic navigation.
+     * Falls back to full page reload for cross-origin URLs.
+     * @param href - The URL to navigate to
+     * @param options - Navigation options
+     * @param options.replace - If true, replaces the current history entry instead of pushing
+     */
+    navigate(href: string, options?: {
+        replace?: boolean;
+    }): Promise<void>;
+    /**
+     * Manually prefetch a URL.
+     * @param href - The URL to prefetch
+     */
+    prefetch(href: string): Promise<void>;
+    /**
+     * Intercepts link clicks for client-side navigation.
+     *
+     * Filters out clicks with modifier keys (opens new tab), non-left clicks,
+     * external links, download links, and links with the reload attribute.
+     *
+     * Uses `event.composedPath()` to correctly detect clicks on anchors inside
+     * Shadow DOM boundaries (Web Components).
+     */
+    private handleClick;
+    /**
+     * Handles browser back/forward navigation.
+     * Triggered by the History API's popstate event.
+     */
+    private handlePopState;
+    /**
+     * Checks if a URL shares the same origin as the current page.
+     * Cross-origin navigation always falls back to full page reload.
+     */
+    private isSameOrigin;
+    /**
+     * Executes the core navigation flow.
+     *
+     * Orchestrates fetching, DOM swapping, and lifecycle events:
+     *
+     * 1. **Fetch** - Retrieves HTML (from cache or network)
+     * 2. **eco:before-swap** - Allows listeners to force a full reload
+     * 3. **History update** - Updates URL before DOM swap so Web Components
+     *    see the correct URL in their `connectedCallback`
+     * 4. **Stylesheet preload** - Prevents FOUC by loading styles first
+     * 5. **DOM swap** - Morphs head/body, optionally with View Transition
+     * 6. **Lifecycle events** - Dispatches `eco:after-swap` and `eco:page-load`
+     *
+     * Falls back to full page reload on network errors.
+     *
+     * @param url - The target URL to navigate to
+     * @param direction - Navigation direction ('forward', 'back', or 'replace')
+     */
+    private performNavigation;
+    /**
+     * Fetches the HTML content of a page.
+     * @param url - The URL to fetch
+     * @param signal - AbortSignal for cancelling the request
+     * @throws Error if the response is not ok
+     */
+    private fetchPage;
+}
+/**
+ * Creates and starts a router instance.
+ * @param options - Configuration options for the router
+ * @returns A started EcoRouter instance
+ */
+export declare function createRouter(options?: EcoRouterOptions): EcoRouter;
+export type { EcoRouterOptions, EcoNavigationEvent, EcoBeforeSwapEvent, EcoAfterSwapEvent } from './types';

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

@@ -0,0 +1,228 @@
+import { DEFAULT_OPTIONS } from "./types.js";
+import { DomSwapper, ScrollManager, ViewTransitionManager, PrefetchManager } from "./services/index.js";
+class EcoRouter {
+  options;
+  abortController = null;
+  domSwapper;
+  scrollManager;
+  viewTransitionManager;
+  prefetchManager = null;
+  constructor(options = {}) {
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.domSwapper = new DomSwapper(this.options.persistAttribute);
+    this.scrollManager = new ScrollManager(this.options.scrollBehavior, this.options.smoothScroll);
+    this.viewTransitionManager = new ViewTransitionManager(this.options.viewTransitions);
+    if (this.options.prefetch !== false) {
+      this.prefetchManager = new PrefetchManager({
+        ...this.options.prefetch,
+        linkSelector: this.options.linkSelector
+      });
+    }
+    this.handleClick = this.handleClick.bind(this);
+    this.handlePopState = this.handlePopState.bind(this);
+  }
+  /**
+   * Starts the router and begins intercepting navigation.
+   *
+   * Attaches click handlers for links and popstate handlers for browser
+   * back/forward buttons. Also starts the prefetch manager if configured.
+   */
+  start() {
+    document.addEventListener("click", this.handleClick);
+    window.addEventListener("popstate", this.handlePopState);
+    this.prefetchManager?.start();
+    const initialHtml = document.documentElement.outerHTML;
+    this.prefetchManager?.cacheVisitedPage(window.location.href, initialHtml);
+  }
+  /**
+   * 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);
+    window.removeEventListener("popstate", this.handlePopState);
+    this.prefetchManager?.stop();
+  }
+  /**
+   * Programmatic navigation.
+   * Falls back to full page reload for cross-origin URLs.
+   * @param href - The URL to navigate to
+   * @param options - Navigation options
+   * @param options.replace - If true, replaces the current history entry instead of pushing
+   */
+  async navigate(href, options = {}) {
+    const url = new URL(href, window.location.origin);
+    if (!this.isSameOrigin(url)) {
+      window.location.href = href;
+      return;
+    }
+    await this.performNavigation(url, options.replace ? "replace" : "forward");
+  }
+  /**
+   * Manually prefetch a URL.
+   * @param href - The URL to prefetch
+   */
+  async prefetch(href) {
+    if (!this.prefetchManager) {
+      console.warn("[ecopages] Prefetching is disabled. Enable it in router options.");
+      return;
+    }
+    return this.prefetchManager.prefetch(href);
+  }
+  /**
+   * Intercepts link clicks for client-side navigation.
+   *
+   * Filters out clicks with modifier keys (opens new tab), non-left clicks,
+   * external links, download links, and links with the reload attribute.
+   *
+   * Uses `event.composedPath()` to correctly detect clicks on anchors inside
+   * Shadow DOM boundaries (Web Components).
+   */
+  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");
+    if (!href) return;
+    if (href.startsWith("#")) return;
+    if (href.startsWith("javascript:")) return;
+    const url = new URL(href, window.location.origin);
+    if (!this.isSameOrigin(url)) return;
+    event.preventDefault();
+    this.performNavigation(url, "forward");
+  }
+  /**
+   * Handles browser back/forward navigation.
+   * Triggered by the History API's popstate event.
+   */
+  handlePopState(_event) {
+    const url = new URL(window.location.href);
+    this.performNavigation(url, "back");
+  }
+  /**
+   * Checks if a URL shares the same origin as the current page.
+   * Cross-origin navigation always falls back to full page reload.
+   */
+  isSameOrigin(url) {
+    return url.origin === window.location.origin;
+  }
+  /**
+   * Executes the core navigation flow.
+   *
+   * Orchestrates fetching, DOM swapping, and lifecycle events:
+   *
+   * 1. **Fetch** - Retrieves HTML (from cache or network)
+   * 2. **eco:before-swap** - Allows listeners to force a full reload
+   * 3. **History update** - Updates URL before DOM swap so Web Components
+   *    see the correct URL in their `connectedCallback`
+   * 4. **Stylesheet preload** - Prevents FOUC by loading styles first
+   * 5. **DOM swap** - Morphs head/body, optionally with View Transition
+   * 6. **Lifecycle events** - Dispatches `eco:after-swap` and `eco:page-load`
+   *
+   * Falls back to full page reload on network errors.
+   *
+   * @param url - The target URL to navigate to
+   * @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();
+    try {
+      const html = await this.fetchPage(url, this.abortController.signal);
+      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 }
+          })
+        );
+      });
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        return;
+      }
+      console.error("[ecopages] Navigation failed:", error);
+      window.location.href = url.href;
+    }
+  }
+  /**
+   * Fetches the HTML content of a page.
+   * @param url - The URL to fetch
+   * @param signal - AbortSignal for cancelling the request
+   * @throws Error if the response is not ok
+   */
+  async fetchPage(url, signal) {
+    if (this.prefetchManager) {
+      const cachedHtml = this.prefetchManager.getCachedHtml(url.href);
+      if (cachedHtml) {
+        return cachedHtml;
+      }
+    }
+    const response = await fetch(url.href, {
+      signal,
+      headers: {
+        Accept: "text/html"
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`Failed to fetch page: ${response.status}`);
+    }
+    return response.text();
+  }
+}
+function createRouter(options) {
+  const router = new EcoRouter(options);
+  router.start();
+  return router;
+}
+export {
+  EcoRouter,
+  createRouter
+};