eleva 1.0.0-alpha → 1.0.0-rc.10

package/dist/plugins/router.umd.js

@@ -0,0 +1,1807 @@
+/*! Eleva Router Plugin v1.0.0-rc.10 | MIT License | https://elevajs.com */
+(function (global, factory) {
+  typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
+  typeof define === 'function' && define.amd ? define(['exports'], factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.ElevaRouterPlugin = {}));
+})(this, (function (exports) { 'use strict';
+
+  /**
+   * @typedef {import('eleva').Eleva} Eleva
+   * @typedef {import('eleva').Signal} Signal
+   * @typedef {import('eleva').ComponentDefinition} ComponentDefinition
+   * @typedef {import('eleva').Emitter} Emitter
+   * @typedef {import('eleva').MountResult} MountResult
+   */
+
+  // ============================================
+  // Core Type Definitions
+  // ============================================
+
+  /**
+   * @typedef {'hash' | 'history' | 'query'} RouterMode
+   * The routing mode determines how the router manages URL state.
+   * - `hash`: Uses URL hash (e.g., `/#/path`) - works without server config
+   * - `history`: Uses HTML5 History API (e.g., `/path`) - requires server config
+   * - `query`: Uses query parameters (e.g., `?view=/path`) - useful for embedded apps
+   */
+
+  /**
+   * @typedef {Object} RouterOptions
+   * @property {RouterMode} [mode='hash'] - The routing mode to use.
+   * @property {string} [queryParam='view'] - Query parameter name for 'query' mode.
+   * @property {string} [viewSelector='root'] - Selector for the view container element.
+   * @property {string} mount - CSS selector for the mount point element.
+   * @property {RouteDefinition[]} routes - Array of route definitions.
+   * @property {string | ComponentDefinition} [globalLayout] - Default layout for all routes.
+   * @property {NavigationGuard} [onBeforeEach] - Global navigation guard.
+   * @description Configuration options for the Router plugin.
+   */
+
+  /**
+   * @typedef {Object} NavigationTarget
+   * @property {string} path - The target path (can include params like '/users/:id').
+   * @property {Record<string, string>} [params] - Route parameters to inject into the path.
+   * @property {Record<string, string>} [query] - Query parameters to append.
+   * @property {boolean} [replace=false] - Whether to replace current history entry.
+   * @property {Record<string, any>} [state] - State object to pass to history.
+   * @description Object describing a navigation target for `router.navigate()`.
+   */
+
+  /**
+   * @typedef {Object} ScrollPosition
+   * @property {number} x - Horizontal scroll position.
+   * @property {number} y - Vertical scroll position.
+   * @description Represents a saved scroll position.
+   */
+
+  /**
+   * @typedef {Object} RouteSegment
+   * @property {'static' | 'param'} type - The segment type.
+   * @property {string} value - The segment value (for static) or empty string (for param).
+   * @property {string} [name] - The parameter name (for param segments).
+   * @description Internal representation of a parsed route path segment.
+   * @private
+   */
+
+  /**
+   * @typedef {Object} RouteMatch
+   * @property {RouteDefinition} route - The matched route definition.
+   * @property {Record<string, string>} params - The extracted route parameters.
+   * @description Result of matching a path against route definitions.
+   * @private
+   */
+
+  /**
+   * @typedef {Record<string, any>} RouteMeta
+   * @description Arbitrary metadata attached to routes for use in guards and components.
+   * Common properties include:
+   * - `requiresAuth: boolean` - Whether the route requires authentication
+   * - `title: string` - Page title for the route
+   * - `roles: string[]` - Required user roles
+   * @example
+   * {
+   *   path: '/admin',
+   *   component: AdminPage,
+   *   meta: { requiresAuth: true, roles: ['admin'], title: 'Admin Dashboard' }
+   * }
+   */
+
+  /**
+   * @typedef {Object} RouterErrorHandler
+   * @property {(error: Error, context: string, details?: Record<string, any>) => void} handle - Throws a formatted error.
+   * @property {(message: string, details?: Record<string, any>) => void} warn - Logs a warning.
+   * @property {(message: string, error: Error, details?: Record<string, any>) => void} log - Logs an error without throwing.
+   * @description Interface for the router's error handling system.
+   */
+
+  // ============================================
+  // Event Callback Type Definitions
+  // ============================================
+
+  /**
+   * @callback NavigationContextCallback
+   * @param {NavigationContext} context - The navigation context (can be modified to block/redirect).
+   * @returns {void | Promise<void>}
+   * @description Callback for `router:beforeEach` event. Modify context to control navigation.
+   */
+
+  /**
+   * @callback ResolveContextCallback
+   * @param {ResolveContext} context - The resolve context (can be modified to block/redirect).
+   * @returns {void | Promise<void>}
+   * @description Callback for `router:beforeResolve` and `router:afterResolve` events.
+   */
+
+  /**
+   * @callback RenderContextCallback
+   * @param {RenderContext} context - The render context.
+   * @returns {void | Promise<void>}
+   * @description Callback for `router:beforeRender` and `router:afterRender` events.
+   */
+
+  /**
+   * @callback ScrollContextCallback
+   * @param {ScrollContext} context - The scroll context with saved position info.
+   * @returns {void | Promise<void>}
+   * @description Callback for `router:scroll` event. Use to implement scroll behavior.
+   */
+
+  /**
+   * @callback RouteChangeCallback
+   * @param {RouteLocation} to - The target route location.
+   * @param {RouteLocation | null} from - The source route location.
+   * @returns {void | Promise<void>}
+   * @description Callback for `router:afterEnter`, `router:afterLeave`, `router:afterEach` events.
+   */
+
+  /**
+   * @callback RouterErrorCallback
+   * @param {Error} error - The error that occurred.
+   * @param {RouteLocation} [to] - The target route (if available).
+   * @param {RouteLocation | null} [from] - The source route (if available).
+   * @returns {void | Promise<void>}
+   * @description Callback for `router:onError` event.
+   */
+
+  /**
+   * @callback RouterReadyCallback
+   * @param {Router} router - The router instance.
+   * @returns {void | Promise<void>}
+   * @description Callback for `router:ready` event.
+   */
+
+  /**
+   * @callback RouteAddedCallback
+   * @param {RouteDefinition} route - The added route definition.
+   * @returns {void | Promise<void>}
+   * @description Callback for `router:routeAdded` event.
+   */
+
+  /**
+   * @callback RouteRemovedCallback
+   * @param {RouteDefinition} route - The removed route definition.
+   * @returns {void | Promise<void>}
+   * @description Callback for `router:routeRemoved` event.
+   */
+
+  // ============================================
+  // Core Type Definitions (continued)
+  // ============================================
+
+  /**
+   * Simple error handler for the core router.
+   * Can be overridden by error handling plugins.
+   * Provides consistent error formatting and logging for router operations.
+   * @private
+   */
+  const CoreErrorHandler = {
+    /**
+     * Handles router errors with basic formatting.
+     * @param {Error} error - The error to handle.
+     * @param {string} context - The context where the error occurred.
+     * @param {Object} details - Additional error details.
+     * @throws {Error} The formatted error.
+     */
+    handle(error, context, details = {}) {
+      const message = `[ElevaRouter] ${context}: ${error.message}`;
+      const formattedError = new Error(message);
+
+      // Preserve original error details
+      formattedError.originalError = error;
+      formattedError.context = context;
+      formattedError.details = details;
+      console.error(message, {
+        error,
+        context,
+        details
+      });
+      throw formattedError;
+    },
+    /**
+     * Logs a warning without throwing an error.
+     * @param {string} message - The warning message.
+     * @param {Object} details - Additional warning details.
+     */
+    warn(message, details = {}) {
+      console.warn(`[ElevaRouter] ${message}`, details);
+    },
+    /**
+     * Logs an error without throwing.
+     * @param {string} message - The error message.
+     * @param {Error} error - The original error.
+     * @param {Object} details - Additional error details.
+     */
+    log(message, error, details = {}) {
+      console.error(`[ElevaRouter] ${message}`, {
+        error,
+        details
+      });
+    }
+  };
+
+  /**
+   * @typedef {Object} RouteLocation
+   * @property {string} path - The path of the route (e.g., '/users/123').
+   * @property {Record<string, string>} query - Query parameters as key-value pairs.
+   * @property {string} fullUrl - The complete URL including hash, path, and query string.
+   * @property {Record<string, string>} params - Dynamic route parameters (e.g., `{ id: '123' }`).
+   * @property {RouteMeta} meta - Metadata associated with the matched route.
+   * @property {string} [name] - The optional name of the matched route.
+   * @property {RouteDefinition} matched - The raw route definition object that was matched.
+   * @description Represents the current or target location in the router.
+   */
+
+  /**
+   * @typedef {boolean | string | NavigationTarget | void} NavigationGuardResult
+   * The return value of a navigation guard.
+   * - `true` or `undefined/void`: Allow navigation
+   * - `false`: Abort navigation
+   * - `string`: Redirect to path
+   * - `NavigationTarget`: Redirect with options
+   */
+
+  /**
+   * @callback NavigationGuard
+   * @param {RouteLocation} to - The target route location.
+   * @param {RouteLocation | null} from - The source route location (null on initial navigation).
+   * @returns {NavigationGuardResult | Promise<NavigationGuardResult>}
+   * @description A function that controls navigation flow. Runs before navigation is confirmed.
+   * @example
+   * // Simple auth guard
+   * const authGuard = (to, from) => {
+   *   if (to.meta.requiresAuth && !isLoggedIn()) {
+   *     return '/login'; // Redirect
+   *   }
+   *   // Allow navigation (implicit return undefined)
+   * };
+   */
+
+  /**
+   * @callback NavigationHook
+   * @param {RouteLocation} to - The target route location.
+   * @param {RouteLocation | null} from - The source route location.
+   * @returns {void | Promise<void>}
+   * @description A lifecycle hook for side effects. Does not affect navigation flow.
+   * @example
+   * // Analytics hook
+   * const analyticsHook = (to, from) => {
+   *   analytics.trackPageView(to.path);
+   * };
+   */
+
+  /**
+   * @typedef {Object} RouterPlugin
+   * @property {string} name - Unique plugin identifier.
+   * @property {string} [version] - Plugin version (recommended to match router version).
+   * @property {(router: Router, options?: Record<string, any>) => void} install - Installation function.
+   * @property {(router: Router) => void | Promise<void>} [destroy] - Cleanup function called on router.destroy().
+   * @description Interface for router plugins. Plugins can extend router functionality.
+   * @example
+   * const AnalyticsPlugin = {
+   *   name: 'analytics',
+   *   version: '1.0.0',
+   *   install(router, options) {
+   *     router.emitter.on('router:afterEach', (to, from) => {
+   *       analytics.track(to.path);
+   *     });
+   *   }
+   * };
+   */
+
+  /**
+   * @typedef {Object} NavigationContext
+   * @property {RouteLocation} to - The target route location.
+   * @property {RouteLocation | null} from - The source route location.
+   * @property {boolean} cancelled - Whether navigation has been cancelled.
+   * @property {string | {path: string} | null} redirectTo - Redirect target if navigation should redirect.
+   * @description A context object passed to navigation events that plugins can modify to control navigation flow.
+   */
+
+  /**
+   * @typedef {Object} ResolveContext
+   * @property {RouteLocation} to - The target route location.
+   * @property {RouteLocation | null} from - The source route location.
+   * @property {RouteDefinition} route - The matched route definition.
+   * @property {ComponentDefinition | null} layoutComponent - The resolved layout component (available in afterResolve).
+   * @property {ComponentDefinition | null} pageComponent - The resolved page component (available in afterResolve).
+   * @property {boolean} cancelled - Whether navigation has been cancelled.
+   * @property {string | {path: string} | null} redirectTo - Redirect target if navigation should redirect.
+   * @description A context object passed to component resolution events.
+   */
+
+  /**
+   * @typedef {Object} RenderContext
+   * @property {RouteLocation} to - The target route location.
+   * @property {RouteLocation | null} from - The source route location.
+   * @property {ComponentDefinition | null} layoutComponent - The layout component being rendered.
+   * @property {ComponentDefinition} pageComponent - The page component being rendered.
+   * @description A context object passed to render events.
+   */
+
+  /**
+   * @typedef {Object} ScrollContext
+   * @property {RouteLocation} to - The target route location.
+   * @property {RouteLocation | null} from - The source route location.
+   * @property {{x: number, y: number} | null} savedPosition - The saved scroll position (if navigating via back/forward).
+   * @description A context object passed to scroll events for plugins to handle scroll behavior.
+   */
+
+  /**
+   * @typedef {string | ComponentDefinition | (() => Promise<{default: ComponentDefinition}>)} RouteComponent
+   * A component that can be rendered for a route.
+   * - `string`: Name of a registered component
+   * - `ComponentDefinition`: Inline component definition
+   * - `() => Promise<{default: ComponentDefinition}>`: Lazy-loaded component (e.g., `() => import('./Page.js')`)
+   */
+
+  /**
+   * @typedef {Object} RouteDefinition
+   * @property {string} path - URL path pattern. Supports:
+   *   - Static: `'/about'`
+   *   - Dynamic params: `'/users/:id'`
+   *   - Wildcard: `'*'` (catch-all, must be last)
+   * @property {RouteComponent} component - The component to render for this route.
+   * @property {RouteComponent} [layout] - Optional layout component to wrap the route component.
+   * @property {string} [name] - Optional route name for programmatic navigation.
+   * @property {RouteMeta} [meta] - Optional metadata (auth flags, titles, etc.).
+   * @property {NavigationGuard} [beforeEnter] - Route-specific guard before entering.
+   * @property {NavigationHook} [afterEnter] - Hook after entering and component is mounted.
+   * @property {NavigationGuard} [beforeLeave] - Guard before leaving this route.
+   * @property {NavigationHook} [afterLeave] - Hook after leaving and component is unmounted.
+   * @property {RouteSegment[]} [segments] - Internal: parsed path segments (added by router).
+   * @description Defines a route in the application.
+   * @example
+   * // Static route
+   * { path: '/about', component: AboutPage }
+   *
+   * // Dynamic route with params
+   * { path: '/users/:id', component: UserPage, meta: { requiresAuth: true } }
+   *
+   * // Lazy-loaded route with layout
+   * {
+   *   path: '/dashboard',
+   *   component: () => import('./Dashboard.js'),
+   *   layout: DashboardLayout,
+   *   beforeEnter: (to, from) => isLoggedIn() || '/login'
+   * }
+   *
+   * // Catch-all 404 route (must be last)
+   * { path: '*', component: NotFoundPage }
+   */
+
+  /**
+   * @class Router
+   * @classdesc A powerful, reactive, and flexible Router Plugin for Eleva.js.
+   * This class manages all routing logic, including state, navigation, and rendering.
+   *
+   * ## Features
+   * - Multiple routing modes (hash, history, query)
+   * - Reactive route state via Signals
+   * - Navigation guards and lifecycle hooks
+   * - Lazy-loaded components
+   * - Layout system
+   * - Plugin architecture
+   * - Scroll position management
+   *
+   * ## Events Reference
+   * | Event | Callback Type | Can Block | Description |
+   * |-------|--------------|-----------|-------------|
+   * | `router:ready` | {@link RouterReadyCallback} | No | Router initialized |
+   * | `router:beforeEach` | {@link NavigationContextCallback} | Yes | Before guards run |
+   * | `router:beforeResolve` | {@link ResolveContextCallback} | Yes | Before component loading |
+   * | `router:afterResolve` | {@link ResolveContextCallback} | No | After components loaded |
+   * | `router:afterLeave` | {@link RouteChangeCallback} | No | After leaving route |
+   * | `router:beforeRender` | {@link RenderContextCallback} | No | Before DOM update |
+   * | `router:afterRender` | {@link RenderContextCallback} | No | After DOM update |
+   * | `router:scroll` | {@link ScrollContextCallback} | No | For scroll behavior |
+   * | `router:afterEnter` | {@link RouteChangeCallback} | No | After entering route |
+   * | `router:afterEach` | {@link RouteChangeCallback} | No | Navigation complete |
+   * | `router:onError` | {@link RouterErrorCallback} | No | Navigation error |
+   * | `router:routeAdded` | {@link RouteAddedCallback} | No | Dynamic route added |
+   * | `router:routeRemoved` | {@link RouteRemovedCallback} | No | Dynamic route removed |
+   *
+   * ## Reactive Signals
+   * - `currentRoute: Signal<RouteLocation | null>` - Current route info
+   * - `previousRoute: Signal<RouteLocation | null>` - Previous route info
+   * - `currentParams: Signal<Record<string, string>>` - Current route params
+   * - `currentQuery: Signal<Record<string, string>>` - Current query params
+   * - `currentLayout: Signal<MountResult | null>` - Mounted layout instance
+   * - `currentView: Signal<MountResult | null>` - Mounted view instance
+   * - `isReady: Signal<boolean>` - Router readiness state
+   *
+   * @note Internal API Access Policy:
+   * As a core Eleva plugin, the Router may access internal Eleva APIs (prefixed with _)
+   * such as `eleva._components`. This is intentional and these internal APIs are
+   * considered stable for official plugins. Third-party plugins should avoid
+   * accessing internal APIs as they may change without notice.
+   *
+   * @example
+   * // Basic setup
+   * const router = new Router(eleva, {
+   *   mode: 'hash',
+   *   mount: '#app',
+   *   routes: [
+   *     { path: '/', component: HomePage },
+   *     { path: '/users/:id', component: UserPage },
+   *     { path: '*', component: NotFoundPage }
+   *   ]
+   * });
+   *
+   * // Start router
+   * await router.start();
+   *
+   * // Navigate programmatically
+   * const success = await router.navigate('/users/123');
+   *
+   * // Watch for route changes
+   * router.currentRoute.watch((route) => {
+   *   document.title = route?.meta?.title || 'My App';
+   * });
+   *
+   * @private
+   */
+  class Router {
+    /**
+     * Creates an instance of the Router.
+     * @param {Eleva} eleva - The Eleva framework instance.
+     * @param {RouterOptions} options - The configuration options for the router.
+     */
+    constructor(eleva, options = {}) {
+      /** @type {Eleva} The Eleva framework instance. */
+      this.eleva = eleva;
+
+      /** @type {RouterOptions} The merged router options. */
+      this.options = {
+        mode: "hash",
+        queryParam: "view",
+        viewSelector: "root",
+        ...options
+      };
+
+      /** @private @type {RouteDefinition[]} The processed list of route definitions. */
+      this.routes = this._processRoutes(options.routes || []);
+
+      /** @private @type {import('eleva').Emitter} The shared Eleva event emitter for global hooks. */
+      this.emitter = this.eleva.emitter;
+
+      /** @private @type {boolean} A flag indicating if the router has been started. */
+      this.isStarted = false;
+
+      /** @private @type {boolean} A flag to prevent navigation loops from history events. */
+      this._isNavigating = false;
+
+      /** @private @type {number} Counter for tracking navigation operations to prevent race conditions. */
+      this._navigationId = 0;
+
+      /** @private @type {Array<() => void>} A collection of cleanup functions for event listeners. */
+      this.eventListeners = [];
+
+      /** @type {Signal<RouteLocation | null>} A reactive signal holding the current route's information. */
+      this.currentRoute = new this.eleva.signal(null);
+
+      /** @type {Signal<RouteLocation | null>} A reactive signal holding the previous route's information. */
+      this.previousRoute = new this.eleva.signal(null);
+
+      /** @type {Signal<Object<string, string>>} A reactive signal holding the current route's parameters. */
+      this.currentParams = new this.eleva.signal({});
+
+      /** @type {Signal<Object<string, string>>} A reactive signal holding the current route's query parameters. */
+      this.currentQuery = new this.eleva.signal({});
+
+      /** @type {Signal<import('eleva').MountResult | null>} A reactive signal for the currently mounted layout instance. */
+      this.currentLayout = new this.eleva.signal(null);
+
+      /** @type {Signal<import('eleva').MountResult | null>} A reactive signal for the currently mounted view (page) instance. */
+      this.currentView = new this.eleva.signal(null);
+
+      /** @type {Signal<boolean>} A reactive signal indicating if the router is ready (started and initial navigation complete). */
+      this.isReady = new this.eleva.signal(false);
+
+      /** @private @type {Map<string, RouterPlugin>} Map of registered plugins by name. */
+      this.plugins = new Map();
+
+      /** @private @type {Array<NavigationGuard>} Array of global before-each navigation guards. */
+      this._beforeEachGuards = [];
+
+      // If onBeforeEach was provided in options, add it to the guards array
+      if (options.onBeforeEach) {
+        this._beforeEachGuards.push(options.onBeforeEach);
+      }
+
+      /** @type {Object} The error handler instance. Can be overridden by plugins. */
+      this.errorHandler = CoreErrorHandler;
+
+      /** @private @type {Map<string, {x: number, y: number}>} Saved scroll positions by route path. */
+      this._scrollPositions = new Map();
+      this._validateOptions();
+    }
+
+    /**
+     * Validates the provided router options.
+     * @private
+     * @throws {Error} If the routing mode is invalid.
+     */
+    _validateOptions() {
+      if (!["hash", "query", "history"].includes(this.options.mode)) {
+        this.errorHandler.handle(new Error(`Invalid routing mode: ${this.options.mode}. Must be "hash", "query", or "history".`), "Configuration validation failed");
+      }
+    }
+
+    /**
+     * Pre-processes route definitions to parse their path segments for efficient matching.
+     * @private
+     * @param {RouteDefinition[]} routes - The raw route definitions.
+     * @returns {RouteDefinition[]} The processed routes.
+     */
+    _processRoutes(routes) {
+      const processedRoutes = [];
+      for (const route of routes) {
+        try {
+          processedRoutes.push({
+            ...route,
+            segments: this._parsePathIntoSegments(route.path)
+          });
+        } catch (error) {
+          this.errorHandler.warn(`Invalid path in route definition "${route.path || "undefined"}": ${error.message}`, {
+            route,
+            error
+          });
+        }
+      }
+      return processedRoutes;
+    }
+
+    /**
+     * Parses a route path string into an array of static and parameter segments.
+     * @private
+     * @param {string} path - The path pattern to parse.
+     * @returns {Array<{type: 'static' | 'param', value?: string, name?: string}>} An array of segment objects.
+     * @throws {Error} If the route path is not a valid string.
+     */
+    _parsePathIntoSegments(path) {
+      if (!path || typeof path !== "string") {
+        this.errorHandler.handle(new Error("Route path must be a non-empty string"), "Path parsing failed", {
+          path
+        });
+      }
+      const normalizedPath = path.replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+      if (normalizedPath === "/") {
+        return [];
+      }
+      return normalizedPath.split("/").filter(Boolean).map(segment => {
+        if (segment.startsWith(":")) {
+          const paramName = segment.substring(1);
+          if (!paramName) {
+            this.errorHandler.handle(new Error(`Invalid parameter segment: ${segment}`), "Path parsing failed", {
+              segment,
+              path
+            });
+          }
+          return {
+            type: "param",
+            name: paramName
+          };
+        }
+        return {
+          type: "static",
+          value: segment
+        };
+      });
+    }
+
+    /**
+     * Finds the view element within a container using multiple selector strategies.
+     * @private
+     * @param {HTMLElement} container - The parent element to search within.
+     * @returns {HTMLElement} The found view element or the container itself as a fallback.
+     */
+    _findViewElement(container) {
+      const selector = this.options.viewSelector;
+      return container.querySelector(`#${selector}`) || container.querySelector(`.${selector}`) || container.querySelector(`[data-${selector}]`) || container.querySelector(selector) || container;
+    }
+
+    /**
+     * Starts the router, initializes event listeners, and performs the initial navigation.
+     * @returns {Promise<Router>} The router instance for method chaining.
+     *
+     * @example
+     * // Basic usage
+     * await router.start();
+     *
+     * // Method chaining
+     * await router.start().then(r => r.navigate('/home'));
+     *
+     * // Reactive readiness
+     * router.isReady.watch((ready) => {
+     *   if (ready) console.log('Router is ready!');
+     * });
+     */
+    async start() {
+      if (this.isStarted) {
+        this.errorHandler.warn("Router is already started");
+        return this;
+      }
+      if (typeof window === "undefined") {
+        this.errorHandler.warn("Router start skipped: `window` object not available (SSR environment)");
+        return this;
+      }
+      if (typeof document !== "undefined" && !document.querySelector(this.options.mount)) {
+        this.errorHandler.warn(`Mount element "${this.options.mount}" was not found in the DOM. The router will not start.`, {
+          mountSelector: this.options.mount
+        });
+        return this;
+      }
+      const handler = () => this._handleRouteChange();
+      if (this.options.mode === "hash") {
+        window.addEventListener("hashchange", handler);
+        this.eventListeners.push(() => window.removeEventListener("hashchange", handler));
+      } else {
+        window.addEventListener("popstate", handler);
+        this.eventListeners.push(() => window.removeEventListener("popstate", handler));
+      }
+      this.isStarted = true;
+      // Initial navigation is not a popstate event
+      await this._handleRouteChange(false);
+      // Set isReady to true after initial navigation completes
+      this.isReady.value = true;
+      await this.emitter.emit("router:ready", this);
+      return this;
+    }
+
+    /**
+     * Stops the router and cleans up all event listeners and mounted components.
+     * @returns {Promise<void>}
+     */
+    async destroy() {
+      if (!this.isStarted) return;
+
+      // Clean up plugins
+      for (const plugin of this.plugins.values()) {
+        if (typeof plugin.destroy === "function") {
+          try {
+            await plugin.destroy(this);
+          } catch (error) {
+            this.errorHandler.log(`Plugin ${plugin.name} destroy failed`, error);
+          }
+        }
+      }
+      this.eventListeners.forEach(cleanup => cleanup());
+      this.eventListeners = [];
+      if (this.currentLayout.value) {
+        await this.currentLayout.value.unmount();
+      }
+      this.isStarted = false;
+      this.isReady.value = false;
+    }
+
+    /**
+     * Alias for destroy(). Stops the router and cleans up all resources.
+     * Provided for semantic consistency (start/stop pattern).
+     * @returns {Promise<void>}
+     *
+     * @example
+     * await router.start();
+     * // ... later
+     * await router.stop();
+     */
+    async stop() {
+      return this.destroy();
+    }
+
+    /**
+     * Programmatically navigates to a new route.
+     * @param {string | NavigationTarget} location - The target location as a path string or navigation target object.
+     * @param {Record<string, string>} [params] - Route parameters (only used when location is a string).
+     * @returns {Promise<boolean>} True if navigation succeeded, false if blocked by guards or failed.
+     *
+     * @example
+     * // Basic navigation
+     * await router.navigate('/users/123');
+     *
+     * // Check if navigation succeeded
+     * const success = await router.navigate('/protected');
+     * if (!success) {
+     *   console.log('Navigation was blocked by a guard');
+     * }
+     *
+     * // Navigate with options
+     * await router.navigate({
+     *   path: '/users/:id',
+     *   params: { id: '123' },
+     *   query: { tab: 'profile' },
+     *   replace: true
+     * });
+     */
+    async navigate(location, params = {}) {
+      try {
+        const target = typeof location === "string" ? {
+          path: location,
+          params
+        } : location;
+        let path = this._buildPath(target.path, target.params || {});
+        const query = target.query || {};
+        if (Object.keys(query).length > 0) {
+          const queryString = new URLSearchParams(query).toString();
+          if (queryString) path += `?${queryString}`;
+        }
+        if (this._isSameRoute(path, target.params, query)) {
+          return true; // Already at this route, consider it successful
+        }
+        const navigationSuccessful = await this._proceedWithNavigation(path);
+        if (navigationSuccessful) {
+          // Increment navigation ID and capture it for this navigation
+          const currentNavId = ++this._navigationId;
+          this._isNavigating = true;
+          const state = target.state || {};
+          const replace = target.replace || false;
+          const historyMethod = replace ? "replaceState" : "pushState";
+          if (this.options.mode === "hash") {
+            if (replace) {
+              const newUrl = `${window.location.pathname}${window.location.search}#${path}`;
+              window.history.replaceState(state, "", newUrl);
+            } else {
+              window.location.hash = path;
+            }
+          } else {
+            const url = this.options.mode === "query" ? this._buildQueryUrl(path) : path;
+            history[historyMethod](state, "", url);
+          }
+
+          // Only reset the flag if no newer navigation has started
+          queueMicrotask(() => {
+            if (this._navigationId === currentNavId) {
+              this._isNavigating = false;
+            }
+          });
+        }
+        return navigationSuccessful;
+      } catch (error) {
+        this.errorHandler.log("Navigation failed", error);
+        await this.emitter.emit("router:onError", error);
+        return false;
+      }
+    }
+
+    /**
+     * Builds a URL for query mode.
+     * @private
+     * @param {string} path - The path to set as the query parameter.
+     * @returns {string} The full URL with the updated query string.
+     */
+    _buildQueryUrl(path) {
+      const urlParams = new URLSearchParams(window.location.search);
+      urlParams.set(this.options.queryParam, path.split("?")[0]);
+      return `${window.location.pathname}?${urlParams.toString()}`;
+    }
+
+    /**
+     * Checks if the target route is identical to the current route.
+     * @private
+     * @param {string} path - The target path with query string.
+     * @param {object} params - The target params.
+     * @param {object} query - The target query.
+     * @returns {boolean} - True if the routes are the same.
+     */
+    _isSameRoute(path, params, query) {
+      const current = this.currentRoute.value;
+      if (!current) return false;
+      const [targetPath, queryString] = path.split("?");
+      const targetQuery = query || this._parseQuery(queryString || "");
+      return current.path === targetPath && JSON.stringify(current.params) === JSON.stringify(params || {}) && JSON.stringify(current.query) === JSON.stringify(targetQuery);
+    }
+
+    /**
+     * Injects dynamic parameters into a path string.
+     * @private
+     */
+    _buildPath(path, params) {
+      let result = path;
+      for (const [key, value] of Object.entries(params)) {
+        // Fix: Handle special characters and ensure proper encoding
+        const encodedValue = encodeURIComponent(String(value));
+        result = result.replace(new RegExp(`:${key}\\b`, "g"), encodedValue);
+      }
+      return result;
+    }
+
+    /**
+     * The handler for browser-initiated route changes (e.g., back/forward buttons).
+     * @private
+     * @param {boolean} [isPopState=true] - Whether this is a popstate event (back/forward navigation).
+     */
+    async _handleRouteChange(isPopState = true) {
+      if (this._isNavigating) return;
+      try {
+        const from = this.currentRoute.value;
+        const toLocation = this._getCurrentLocation();
+        const navigationSuccessful = await this._proceedWithNavigation(toLocation.fullUrl, isPopState);
+
+        // If navigation was blocked by a guard, revert the URL change
+        if (!navigationSuccessful && from) {
+          this.navigate({
+            path: from.path,
+            query: from.query,
+            replace: true
+          });
+        }
+      } catch (error) {
+        this.errorHandler.log("Route change handling failed", error, {
+          currentUrl: typeof window !== "undefined" ? window.location.href : ""
+        });
+        await this.emitter.emit("router:onError", error);
+      }
+    }
+
+    /**
+     * Manages the core navigation lifecycle. Runs guards before committing changes.
+     * Emits lifecycle events that plugins can hook into:
+     * - router:beforeEach - Before guards run (can block/redirect via context)
+     * - router:beforeResolve - Before component resolution (can block/redirect)
+     * - router:afterResolve - After components are resolved
+     * - router:beforeRender - Before DOM rendering
+     * - router:afterRender - After DOM rendering
+     * - router:scroll - After render, for scroll behavior
+     * - router:afterEnter - After entering a route
+     * - router:afterLeave - After leaving a route
+     * - router:afterEach - After navigation completes
+     *
+     * @private
+     * @param {string} fullPath - The full path (e.g., '/users/123?foo=bar') to navigate to.
+     * @param {boolean} [isPopState=false] - Whether this navigation was triggered by popstate (back/forward).
+     * @returns {Promise<boolean>} - `true` if navigation succeeded, `false` if aborted.
+     */
+    async _proceedWithNavigation(fullPath, isPopState = false) {
+      const from = this.currentRoute.value;
+      const [path, queryString] = (fullPath || "/").split("?");
+      const toLocation = {
+        path: path.startsWith("/") ? path : `/${path}`,
+        query: this._parseQuery(queryString),
+        fullUrl: fullPath
+      };
+      let toMatch = this._matchRoute(toLocation.path);
+      if (!toMatch) {
+        const notFoundRoute = this.routes.find(route => route.path === "*");
+        if (notFoundRoute) {
+          toMatch = {
+            route: notFoundRoute,
+            params: {
+              pathMatch: decodeURIComponent(toLocation.path.substring(1))
+            }
+          };
+        } else {
+          await this.emitter.emit("router:onError", new Error(`Route not found: ${toLocation.path}`), toLocation, from);
+          return false;
+        }
+      }
+      const to = {
+        ...toLocation,
+        params: toMatch.params,
+        meta: toMatch.route.meta || {},
+        name: toMatch.route.name,
+        matched: toMatch.route
+      };
+      try {
+        // 1. Run all *pre-navigation* guards.
+        const canNavigate = await this._runGuards(to, from, toMatch.route);
+        if (!canNavigate) return false;
+
+        // 2. Save current scroll position before navigating away
+        if (from && typeof window !== "undefined") {
+          this._scrollPositions.set(from.path, {
+            x: window.scrollX || window.pageXOffset || 0,
+            y: window.scrollY || window.pageYOffset || 0
+          });
+        }
+
+        // 3. Emit beforeResolve event - plugins can show loading indicators
+        /** @type {ResolveContext} */
+        const resolveContext = {
+          to,
+          from,
+          route: toMatch.route,
+          layoutComponent: null,
+          pageComponent: null,
+          cancelled: false,
+          redirectTo: null
+        };
+        await this.emitter.emit("router:beforeResolve", resolveContext);
+
+        // Check if resolution was cancelled or redirected
+        if (resolveContext.cancelled) return false;
+        if (resolveContext.redirectTo) {
+          this.navigate(resolveContext.redirectTo);
+          return false;
+        }
+
+        // 4. Resolve async components *before* touching the DOM.
+        const {
+          layoutComponent,
+          pageComponent
+        } = await this._resolveComponents(toMatch.route);
+
+        // 5. Emit afterResolve event - plugins can hide loading indicators
+        resolveContext.layoutComponent = layoutComponent;
+        resolveContext.pageComponent = pageComponent;
+        await this.emitter.emit("router:afterResolve", resolveContext);
+
+        // 6. Unmount the previous view/layout.
+        if (from) {
+          const toLayout = toMatch.route.layout || this.options.globalLayout;
+          const fromLayout = from.matched.layout || this.options.globalLayout;
+          const tryUnmount = async instance => {
+            if (!instance) return;
+            try {
+              await instance.unmount();
+            } catch (error) {
+              this.errorHandler.warn("Error during component unmount", {
+                error,
+                instance
+              });
+            }
+          };
+          if (toLayout !== fromLayout) {
+            await tryUnmount(this.currentLayout.value);
+            this.currentLayout.value = null;
+          } else {
+            await tryUnmount(this.currentView.value);
+            this.currentView.value = null;
+          }
+
+          // Call `afterLeave` hook *after* the old component has been unmounted.
+          if (from.matched.afterLeave) {
+            await from.matched.afterLeave(to, from);
+          }
+          await this.emitter.emit("router:afterLeave", to, from);
+        }
+
+        // 7. Update reactive state.
+        this.previousRoute.value = from;
+        this.currentRoute.value = to;
+        this.currentParams.value = to.params || {};
+        this.currentQuery.value = to.query || {};
+
+        // 8. Emit beforeRender event - plugins can add transitions
+        /** @type {RenderContext} */
+        const renderContext = {
+          to,
+          from,
+          layoutComponent,
+          pageComponent
+        };
+        await this.emitter.emit("router:beforeRender", renderContext);
+
+        // 9. Render the new components.
+        await this._render(layoutComponent, pageComponent, to);
+
+        // 10. Emit afterRender event - plugins can trigger animations
+        await this.emitter.emit("router:afterRender", renderContext);
+
+        // 11. Emit scroll event - plugins can handle scroll restoration
+        /** @type {ScrollContext} */
+        const scrollContext = {
+          to,
+          from,
+          savedPosition: isPopState ? this._scrollPositions.get(to.path) || null : null
+        };
+        await this.emitter.emit("router:scroll", scrollContext);
+
+        // 12. Run post-navigation hooks.
+        if (toMatch.route.afterEnter) {
+          await toMatch.route.afterEnter(to, from);
+        }
+        await this.emitter.emit("router:afterEnter", to, from);
+        await this.emitter.emit("router:afterEach", to, from);
+        return true;
+      } catch (error) {
+        this.errorHandler.log("Error during navigation", error, {
+          to,
+          from
+        });
+        await this.emitter.emit("router:onError", error, to, from);
+        return false;
+      }
+    }
+
+    /**
+     * Executes all applicable navigation guards for a transition in order.
+     * Guards are executed in the following order:
+     * 1. Global beforeEach event (emitter-based, can block via context)
+     * 2. Global beforeEach guards (registered via onBeforeEach)
+     * 3. Route-specific beforeLeave guard (from the route being left)
+     * 4. Route-specific beforeEnter guard (from the route being entered)
+     *
+     * @private
+     * @param {RouteLocation} to - The target route location.
+     * @param {RouteLocation | null} from - The current route location (null on initial navigation).
+     * @param {RouteDefinition} route - The matched route definition.
+     * @returns {Promise<boolean>} - `false` if navigation should be aborted.
+     */
+    async _runGuards(to, from, route) {
+      // Create navigation context that plugins can modify to block navigation
+      /** @type {NavigationContext} */
+      const navContext = {
+        to,
+        from,
+        cancelled: false,
+        redirectTo: null
+      };
+
+      // Emit beforeEach event with context - plugins can block by modifying context
+      await this.emitter.emit("router:beforeEach", navContext);
+
+      // Check if navigation was cancelled or redirected by event listeners
+      if (navContext.cancelled) return false;
+      if (navContext.redirectTo) {
+        this.navigate(navContext.redirectTo);
+        return false;
+      }
+
+      // Collect all guards in execution order
+      const guards = [...this._beforeEachGuards, ...(from && from.matched.beforeLeave ? [from.matched.beforeLeave] : []), ...(route.beforeEnter ? [route.beforeEnter] : [])];
+      for (const guard of guards) {
+        const result = await guard(to, from);
+        if (result === false) return false;
+        if (typeof result === "string" || typeof result === "object") {
+          this.navigate(result);
+          return false;
+        }
+      }
+      return true;
+    }
+
+    /**
+     * Resolves a string component definition to a component object.
+     * @private
+     * @param {string} def - The component name to resolve.
+     * @returns {ComponentDefinition} The resolved component.
+     * @throws {Error} If the component is not registered.
+     *
+     * @note Core plugins (Router, Attr, Props, Store) may access eleva._components
+     * directly. This is intentional and stable for official Eleva plugins shipped
+     * with the framework. Third-party plugins should use eleva.component() for
+     * registration and avoid direct access to internal APIs.
+     */
+    _resolveStringComponent(def) {
+      const componentDef = this.eleva._components.get(def);
+      if (!componentDef) {
+        this.errorHandler.handle(new Error(`Component "${def}" not registered.`), "Component resolution failed", {
+          componentName: def,
+          availableComponents: Array.from(this.eleva._components.keys())
+        });
+      }
+      return componentDef;
+    }
+
+    /**
+     * Resolves a function component definition to a component object.
+     * @private
+     * @param {Function} def - The function to resolve.
+     * @returns {Promise<ComponentDefinition>} The resolved component.
+     * @throws {Error} If the function fails to load the component.
+     */
+    async _resolveFunctionComponent(def) {
+      try {
+        const funcStr = def.toString();
+        const isAsyncImport = funcStr.includes("import(") || funcStr.startsWith("() =>");
+        const result = await def();
+        return isAsyncImport ? result.default || result : result;
+      } catch (error) {
+        this.errorHandler.handle(new Error(`Failed to load async component: ${error.message}`), "Component resolution failed", {
+          function: def.toString(),
+          error
+        });
+      }
+    }
+
+    /**
+     * Validates a component definition object.
+     * @private
+     * @param {any} def - The component definition to validate.
+     * @returns {ComponentDefinition} The validated component.
+     * @throws {Error} If the component definition is invalid.
+     */
+    _validateComponentDefinition(def) {
+      if (!def || typeof def !== "object") {
+        this.errorHandler.handle(new Error(`Invalid component definition: ${typeof def}`), "Component validation failed", {
+          definition: def
+        });
+      }
+      if (typeof def.template !== "function" && typeof def.template !== "string") {
+        this.errorHandler.handle(new Error("Component missing template property"), "Component validation failed", {
+          definition: def
+        });
+      }
+      return def;
+    }
+
+    /**
+     * Resolves a component definition to a component object.
+     * @private
+     * @param {any} def - The component definition to resolve.
+     * @returns {Promise<ComponentDefinition | null>} The resolved component or null.
+     */
+    async _resolveComponent(def) {
+      if (def === null || def === undefined) {
+        return null;
+      }
+      if (typeof def === "string") {
+        return this._resolveStringComponent(def);
+      }
+      if (typeof def === "function") {
+        return await this._resolveFunctionComponent(def);
+      }
+      if (def && typeof def === "object") {
+        return this._validateComponentDefinition(def);
+      }
+      this.errorHandler.handle(new Error(`Invalid component definition: ${typeof def}`), "Component resolution failed", {
+        definition: def
+      });
+    }
+
+    /**
+     * Asynchronously resolves the layout and page components for a route.
+     * @private
+     * @param {RouteDefinition} route - The route to resolve components for.
+     * @returns {Promise<{layoutComponent: ComponentDefinition | null, pageComponent: ComponentDefinition}>}
+     */
+    async _resolveComponents(route) {
+      const effectiveLayout = route.layout || this.options.globalLayout;
+      try {
+        const [layoutComponent, pageComponent] = await Promise.all([this._resolveComponent(effectiveLayout), this._resolveComponent(route.component)]);
+        if (!pageComponent) {
+          this.errorHandler.handle(new Error(`Page component is null or undefined for route: ${route.path}`), "Component resolution failed", {
+            route: route.path
+          });
+        }
+        return {
+          layoutComponent,
+          pageComponent
+        };
+      } catch (error) {
+        this.errorHandler.log(`Error resolving components for route ${route.path}`, error, {
+          route: route.path
+        });
+        throw error;
+      }
+    }
+
+    /**
+     * Renders the components for the current route into the DOM.
+     * @private
+     * @param {ComponentDefinition | null} layoutComponent - The pre-loaded layout component.
+     * @param {ComponentDefinition} pageComponent - The pre-loaded page component.
+     */
+    async _render(layoutComponent, pageComponent) {
+      const mountEl = document.querySelector(this.options.mount);
+      if (!mountEl) {
+        this.errorHandler.handle(new Error(`Mount element "${this.options.mount}" not found.`), {
+          mountSelector: this.options.mount
+        });
+      }
+      if (layoutComponent) {
+        const layoutInstance = await this.eleva.mount(mountEl, this._wrapComponentWithChildren(layoutComponent));
+        this.currentLayout.value = layoutInstance;
+        const viewEl = this._findViewElement(layoutInstance.container);
+        const viewInstance = await this.eleva.mount(viewEl, this._wrapComponentWithChildren(pageComponent));
+        this.currentView.value = viewInstance;
+      } else {
+        const viewInstance = await this.eleva.mount(mountEl, this._wrapComponentWithChildren(pageComponent));
+        this.currentView.value = viewInstance;
+        this.currentLayout.value = null;
+      }
+    }
+
+    /**
+     * Creates a getter function for router context properties.
+     * @private
+     * @param {string} property - The property name to access.
+     * @param {any} defaultValue - The default value if property is undefined.
+     * @returns {Function} A getter function.
+     */
+    _createRouteGetter(property, defaultValue) {
+      return () => this.currentRoute.value?.[property] ?? defaultValue;
+    }
+
+    /**
+     * Wraps a component definition to inject router-specific context into its setup function.
+     * @private
+     * @param {ComponentDefinition} component - The component to wrap.
+     * @returns {ComponentDefinition} The wrapped component definition.
+     */
+    _wrapComponent(component) {
+      const originalSetup = component.setup;
+      const self = this;
+      return {
+        ...component,
+        async setup(ctx) {
+          ctx.router = {
+            navigate: self.navigate.bind(self),
+            current: self.currentRoute,
+            previous: self.previousRoute,
+            // Route property getters
+            get params() {
+              return self._createRouteGetter("params", {})();
+            },
+            get query() {
+              return self._createRouteGetter("query", {})();
+            },
+            get path() {
+              return self._createRouteGetter("path", "/")();
+            },
+            get fullUrl() {
+              return self._createRouteGetter("fullUrl", window.location.href)();
+            },
+            get meta() {
+              return self._createRouteGetter("meta", {})();
+            }
+          };
+          return originalSetup ? await originalSetup(ctx) : {};
+        }
+      };
+    }
+
+    /**
+     * Recursively wraps all child components to ensure they have access to router context.
+     * @private
+     * @param {ComponentDefinition | string} component - The component to wrap (can be a definition object or a registered component name).
+     * @returns {ComponentDefinition | string} The wrapped component definition or the original string reference.
+     */
+    _wrapComponentWithChildren(component) {
+      // If the component is a string (registered component name), return as-is
+      // The router context will be injected when the component is resolved during mounting
+      if (typeof component === "string") {
+        return component;
+      }
+
+      // If not a valid component object, return as-is
+      if (!component || typeof component !== "object") {
+        return component;
+      }
+      const wrappedComponent = this._wrapComponent(component);
+
+      // If the component has children, wrap them too
+      if (wrappedComponent.children && typeof wrappedComponent.children === "object") {
+        const wrappedChildren = {};
+        for (const [selector, childComponent] of Object.entries(wrappedComponent.children)) {
+          wrappedChildren[selector] = this._wrapComponentWithChildren(childComponent);
+        }
+        wrappedComponent.children = wrappedChildren;
+      }
+      return wrappedComponent;
+    }
+
+    /**
+     * Gets the current location information from the browser's window object.
+     * @private
+     * @returns {Omit<RouteLocation, 'params' | 'meta' | 'name' | 'matched'>}
+     */
+    _getCurrentLocation() {
+      if (typeof window === "undefined") return {
+        path: "/",
+        query: {},
+        fullUrl: ""
+      };
+      let path, queryString, fullUrl;
+      switch (this.options.mode) {
+        case "hash":
+          fullUrl = window.location.hash.slice(1) || "/";
+          [path, queryString] = fullUrl.split("?");
+          break;
+        case "query":
+          const urlParams = new URLSearchParams(window.location.search);
+          path = urlParams.get(this.options.queryParam) || "/";
+          queryString = window.location.search.slice(1);
+          fullUrl = path;
+          break;
+        default:
+          // 'history' mode
+          path = window.location.pathname || "/";
+          queryString = window.location.search.slice(1);
+          fullUrl = `${path}${queryString ? "?" + queryString : ""}`;
+      }
+      return {
+        path: path.startsWith("/") ? path : `/${path}`,
+        query: this._parseQuery(queryString),
+        fullUrl
+      };
+    }
+
+    /**
+     * Parses a query string into a key-value object.
+     * @private
+     */
+    _parseQuery(queryString) {
+      const query = {};
+      if (queryString) {
+        new URLSearchParams(queryString).forEach((value, key) => {
+          query[key] = value;
+        });
+      }
+      return query;
+    }
+
+    /**
+     * Matches a given path against the registered routes.
+     * @private
+     * @param {string} path - The path to match.
+     * @returns {{route: RouteDefinition, params: Object<string, string>} | null} The matched route and its params, or null.
+     */
+    _matchRoute(path) {
+      const pathSegments = path.split("/").filter(Boolean);
+      for (const route of this.routes) {
+        // Handle the root path as a special case.
+        if (route.path === "/") {
+          if (pathSegments.length === 0) return {
+            route,
+            params: {}
+          };
+          continue;
+        }
+        if (route.segments.length !== pathSegments.length) continue;
+        const params = {};
+        let isMatch = true;
+        for (let i = 0; i < route.segments.length; i++) {
+          const routeSegment = route.segments[i];
+          const pathSegment = pathSegments[i];
+          if (routeSegment.type === "param") {
+            params[routeSegment.name] = decodeURIComponent(pathSegment);
+          } else if (routeSegment.value !== pathSegment) {
+            isMatch = false;
+            break;
+          }
+        }
+        if (isMatch) return {
+          route,
+          params
+        };
+      }
+      return null;
+    }
+
+    // ============================================
+    // Dynamic Route Management API
+    // ============================================
+
+    /**
+     * Adds a new route dynamically at runtime.
+     * The route will be processed and available for navigation immediately.
+     *
+     * @param {RouteDefinition} route - The route definition to add.
+     * @param {RouteDefinition} [parentRoute] - Optional parent route to add as a child (not yet implemented).
+     * @returns {() => void} A function to remove the added route.
+     *
+     * @example
+     * // Add a route dynamically
+     * const removeRoute = router.addRoute({
+     *   path: '/dynamic',
+     *   component: DynamicPage,
+     *   meta: { title: 'Dynamic Page' }
+     * });
+     *
+     * // Later, remove the route
+     * removeRoute();
+     */
+    addRoute(route, parentRoute = null) {
+      if (!route || !route.path) {
+        this.errorHandler.warn("Invalid route definition: missing path", {
+          route
+        });
+        return () => {};
+      }
+
+      // Check if route already exists
+      if (this.hasRoute(route.path)) {
+        this.errorHandler.warn(`Route "${route.path}" already exists`, {
+          route
+        });
+        return () => {};
+      }
+
+      // Process the route (parse segments)
+      const processedRoute = {
+        ...route,
+        segments: this._parsePathIntoSegments(route.path)
+      };
+
+      // Add to routes array (before wildcard if exists)
+      const wildcardIndex = this.routes.findIndex(r => r.path === "*");
+      if (wildcardIndex !== -1) {
+        this.routes.splice(wildcardIndex, 0, processedRoute);
+      } else {
+        this.routes.push(processedRoute);
+      }
+
+      // Emit event for plugins
+      this.emitter.emit("router:routeAdded", processedRoute);
+
+      // Return removal function
+      return () => this.removeRoute(route.path);
+    }
+
+    /**
+     * Removes a route by its path.
+     *
+     * @param {string} path - The path of the route to remove.
+     * @returns {boolean} True if the route was removed, false if not found.
+     *
+     * @example
+     * router.removeRoute('/dynamic');
+     */
+    removeRoute(path) {
+      const index = this.routes.findIndex(r => r.path === path);
+      if (index === -1) {
+        return false;
+      }
+      const [removedRoute] = this.routes.splice(index, 1);
+
+      // Emit event for plugins
+      this.emitter.emit("router:routeRemoved", removedRoute);
+      return true;
+    }
+
+    /**
+     * Checks if a route with the given path exists.
+     *
+     * @param {string} path - The path to check.
+     * @returns {boolean} True if the route exists.
+     *
+     * @example
+     * if (router.hasRoute('/users/:id')) {
+     *   console.log('User route exists');
+     * }
+     */
+    hasRoute(path) {
+      return this.routes.some(r => r.path === path);
+    }
+
+    /**
+     * Gets all registered routes.
+     *
+     * @returns {RouteDefinition[]} A copy of the routes array.
+     *
+     * @example
+     * const routes = router.getRoutes();
+     * console.log('Available routes:', routes.map(r => r.path));
+     */
+    getRoutes() {
+      return [...this.routes];
+    }
+
+    /**
+     * Gets a route by its path.
+     *
+     * @param {string} path - The path of the route to get.
+     * @returns {RouteDefinition | undefined} The route definition or undefined.
+     *
+     * @example
+     * const route = router.getRoute('/users/:id');
+     * if (route) {
+     *   console.log('Route meta:', route.meta);
+     * }
+     */
+    getRoute(path) {
+      return this.routes.find(r => r.path === path);
+    }
+
+    // ============================================
+    // Hook Registration Methods
+    // ============================================
+
+    /**
+     * Registers a global pre-navigation guard.
+     * Multiple guards can be registered and will be executed in order.
+     * Guards can also be registered via the emitter using `router:beforeEach` event.
+     *
+     * @param {NavigationGuard} guard - The guard function to register.
+     * @returns {() => void} A function to unregister the guard.
+     *
+     * @example
+     * // Register a guard
+     * const unregister = router.onBeforeEach((to, from) => {
+     *   if (to.meta.requiresAuth && !isAuthenticated()) {
+     *     return '/login';
+     *   }
+     * });
+     *
+     * // Later, unregister the guard
+     * unregister();
+     */
+    onBeforeEach(guard) {
+      this._beforeEachGuards.push(guard);
+      return () => {
+        const index = this._beforeEachGuards.indexOf(guard);
+        if (index > -1) {
+          this._beforeEachGuards.splice(index, 1);
+        }
+      };
+    }
+    /**
+     * Registers a global hook that runs after a new route component has been mounted.
+     * @param {NavigationHook} hook - The hook function to register.
+     * @returns {() => void} A function to unregister the hook.
+     */
+    onAfterEnter(hook) {
+      return this.emitter.on("router:afterEnter", hook);
+    }
+
+    /**
+     * Registers a global hook that runs after a route component has been unmounted.
+     * @param {NavigationHook} hook - The hook function to register.
+     * @returns {() => void} A function to unregister the hook.
+     */
+    onAfterLeave(hook) {
+      return this.emitter.on("router:afterLeave", hook);
+    }
+
+    /**
+     * Registers a global hook that runs after a navigation has been confirmed and all hooks have completed.
+     * @param {NavigationHook} hook - The hook function to register.
+     * @returns {() => void} A function to unregister the hook.
+     */
+    onAfterEach(hook) {
+      return this.emitter.on("router:afterEach", hook);
+    }
+
+    /**
+     * Registers a global error handler for navigation errors.
+     * @param {(error: Error, to?: RouteLocation, from?: RouteLocation) => void} handler - The error handler function.
+     * @returns {() => void} A function to unregister the handler.
+     */
+    onError(handler) {
+      return this.emitter.on("router:onError", handler);
+    }
+
+    /**
+     * Registers a plugin with the router.
+     * @param {RouterPlugin} plugin - The plugin to register.
+     */
+    use(plugin, options = {}) {
+      if (typeof plugin.install !== "function") {
+        this.errorHandler.handle(new Error("Plugin must have an install method"), "Plugin registration failed", {
+          plugin
+        });
+      }
+
+      // Check if plugin is already registered
+      if (this.plugins.has(plugin.name)) {
+        this.errorHandler.warn(`Plugin "${plugin.name}" is already registered`, {
+          existingPlugin: this.plugins.get(plugin.name)
+        });
+        return;
+      }
+      this.plugins.set(plugin.name, plugin);
+      plugin.install(this, options);
+    }
+
+    /**
+     * Gets all registered plugins.
+     * @returns {RouterPlugin[]} Array of registered plugins.
+     */
+    getPlugins() {
+      return Array.from(this.plugins.values());
+    }
+
+    /**
+     * Gets a plugin by name.
+     * @param {string} name - The plugin name.
+     * @returns {RouterPlugin | undefined} The plugin or undefined.
+     */
+    getPlugin(name) {
+      return this.plugins.get(name);
+    }
+
+    /**
+     * Removes a plugin from the router.
+     * @param {string} name - The plugin name.
+     * @returns {boolean} True if the plugin was removed.
+     */
+    removePlugin(name) {
+      const plugin = this.plugins.get(name);
+      if (!plugin) return false;
+
+      // Call destroy if available
+      if (typeof plugin.destroy === "function") {
+        try {
+          plugin.destroy(this);
+        } catch (error) {
+          this.errorHandler.log(`Plugin ${name} destroy failed`, error);
+        }
+      }
+      return this.plugins.delete(name);
+    }
+
+    /**
+     * Sets a custom error handler. Used by error handling plugins.
+     * @param {Object} errorHandler - The error handler object with handle, warn, and log methods.
+     */
+    setErrorHandler(errorHandler) {
+      if (errorHandler && typeof errorHandler.handle === "function" && typeof errorHandler.warn === "function" && typeof errorHandler.log === "function") {
+        this.errorHandler = errorHandler;
+      } else {
+        console.warn("[ElevaRouter] Invalid error handler provided. Must have handle, warn, and log methods.");
+      }
+    }
+  }
+
+  /**
+   * @typedef {Object} RouterOptions
+   * @property {string} mount - A CSS selector for the main element where the app is mounted.
+   * @property {RouteDefinition[]} routes - An array of route definitions.
+   * @property {'hash' | 'query' | 'history'} [mode='hash'] - The routing mode.
+   * @property {string} [queryParam='page'] - The query parameter to use in 'query' mode.
+   * @property {string} [viewSelector='view'] - The selector for the view element within a layout.
+   * @property {boolean} [autoStart=true] - Whether to start the router automatically.
+   * @property {NavigationGuard} [onBeforeEach] - A global guard executed before every navigation.
+   * @property {string | ComponentDefinition | (() => Promise<{default: ComponentDefinition}>)} [globalLayout] - A global layout for all routes. Can be overridden by a route's specific layout.
+   */
+
+  /**
+   * @class 🚀 RouterPlugin
+   * @classdesc A powerful, reactive, and flexible Router Plugin for Eleva.js applications.
+   * This plugin provides comprehensive client-side routing functionality including:
+   * - Multiple routing modes (hash, history, query)
+   * - Navigation guards and lifecycle hooks
+   * - Reactive state management
+   * - Component resolution and lazy loading
+   * - Layout and page component separation
+   * - Plugin system for extensibility
+   * - Advanced error handling
+   *
+   * @example
+   * // Install the plugin
+   * const app = new Eleva("myApp");
+   *
+   * const HomePage = { template: () => `<h1>Home</h1>` };
+   * const AboutPage = { template: () => `<h1>About Us</h1>` };
+   * const UserPage = {
+   *   template: (ctx) => `<h1>User: ${ctx.router.params.id}</h1>`
+   * };
+   *
+   * app.use(RouterPlugin, {
+   *   mount: '#app',
+   *   mode: 'hash',
+   *   routes: [
+   *     { path: '/', component: HomePage },
+   *     { path: '/about', component: AboutPage },
+   *     { path: '/users/:id', component: UserPage }
+   *   ]
+   * });
+   */
+  const RouterPlugin = {
+    /**
+     * Unique identifier for the plugin
+     * @type {string}
+     */
+    name: "router",
+    /**
+     * Plugin version
+     * @type {string}
+     */
+    version: "1.0.0-rc.10",
+    /**
+     * Plugin description
+     * @type {string}
+     */
+    description: "Client-side routing for Eleva applications",
+    /**
+     * Installs the RouterPlugin into an Eleva instance.
+     *
+     * @param {Eleva} eleva - The Eleva instance
+     * @param {RouterOptions} options - Router configuration options
+     * @param {string} options.mount - A CSS selector for the main element where the app is mounted
+     * @param {RouteDefinition[]} options.routes - An array of route definitions
+     * @param {'hash' | 'query' | 'history'} [options.mode='hash'] - The routing mode
+     * @param {string} [options.queryParam='page'] - The query parameter to use in 'query' mode
+     * @param {string} [options.viewSelector='view'] - The selector for the view element within a layout
+     * @param {boolean} [options.autoStart=true] - Whether to start the router automatically
+     * @param {NavigationGuard} [options.onBeforeEach] - A global guard executed before every navigation
+     * @param {string | ComponentDefinition | (() => Promise<{default: ComponentDefinition}>)} [options.globalLayout] - A global layout for all routes
+     *
+     * @example
+     * // main.js
+     * import Eleva from './eleva.js';
+     * import { RouterPlugin } from './plugins/RouterPlugin.js';
+     *
+     * const app = new Eleva('myApp');
+     *
+     * const HomePage = { template: () => `<h1>Home</h1>` };
+     * const AboutPage = { template: () => `<h1>About Us</h1>` };
+     *
+     * app.use(RouterPlugin, {
+     *  mount: '#app',
+     *  routes: [
+     *    { path: '/', component: HomePage },
+     *    { path: '/about', component: AboutPage }
+     *  ]
+     * });
+     */
+    install(eleva, options = {}) {
+      if (!options.mount) {
+        throw new Error("[RouterPlugin] 'mount' option is required");
+      }
+      if (!options.routes || !Array.isArray(options.routes)) {
+        throw new Error("[RouterPlugin] 'routes' option must be an array");
+      }
+
+      /**
+       * Registers a component definition with the Eleva instance.
+       * This method handles both inline component objects and pre-registered component names.
+       *
+       * @param {any} def - The component definition to register
+       * @param {string} type - The type of component for naming (e.g., "Route", "Layout")
+       * @returns {string | null} The registered component name or null if no definition provided
+       */
+      const register = (def, type) => {
+        if (!def) return null;
+        if (typeof def === "object" && def !== null && !def.name) {
+          const name = `Eleva${type}Component_${Math.random().toString(36).slice(2, 11)}`;
+          try {
+            eleva.component(name, def);
+            return name;
+          } catch (error) {
+            throw new Error(`[RouterPlugin] Failed to register ${type} component: ${error.message}`);
+          }
+        }
+        return def;
+      };
+      if (options.globalLayout) {
+        options.globalLayout = register(options.globalLayout, "GlobalLayout");
+      }
+      (options.routes || []).forEach(route => {
+        route.component = register(route.component, "Route");
+        if (route.layout) {
+          route.layout = register(route.layout, "RouteLayout");
+        }
+      });
+      const router = new Router(eleva, options);
+      eleva.router = router;
+      if (options.autoStart !== false) {
+        queueMicrotask(() => router.start());
+      }
+
+      // Add plugin metadata to the Eleva instance
+      if (!eleva.plugins) {
+        eleva.plugins = new Map();
+      }
+      eleva.plugins.set(this.name, {
+        name: this.name,
+        version: this.version,
+        description: this.description,
+        options
+      });
+
+      // Add utility methods for manual router access
+      eleva.navigate = router.navigate.bind(router);
+      eleva.getCurrentRoute = () => router.currentRoute.value;
+      eleva.getRouteParams = () => router.currentParams.value;
+      eleva.getRouteQuery = () => router.currentQuery.value;
+      return router;
+    },
+    /**
+     * Uninstalls the plugin from the Eleva instance
+     *
+     * @param {Eleva} eleva - The Eleva instance
+     */
+    async uninstall(eleva) {
+      if (eleva.router) {
+        await eleva.router.destroy();
+        delete eleva.router;
+      }
+
+      // Remove plugin metadata
+      if (eleva.plugins) {
+        eleva.plugins.delete(this.name);
+      }
+
+      // Remove utility methods
+      delete eleva.navigate;
+      delete eleva.getCurrentRoute;
+      delete eleva.getRouteParams;
+      delete eleva.getRouteQuery;
+    }
+  };
+
+  exports.RouterPlugin = RouterPlugin;
+
+}));
+//# sourceMappingURL=router.umd.js.map