eleva 1.0.0-alpha → 1.0.0-rc.10

package/dist/eleva-plugins.umd.js

@@ -0,0 +1,3403 @@
+/*! Eleva Plugins 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.ElevaPlugins = {}));
+})(this, (function (exports) { 'use strict';
+
+  /**
+   * A regular expression to match hyphenated lowercase letters.
+   * @private
+   * @type {RegExp}
+   */
+  const CAMEL_RE = /-([a-z])/g;
+
+  /**
+   * @class 🎯 AttrPlugin
+   * @classdesc A plugin that provides advanced attribute handling for Eleva components.
+   * This plugin extends the renderer with sophisticated attribute processing including:
+   * - ARIA attribute handling with proper property mapping
+   * - Data attribute management
+   * - Boolean attribute processing
+   * - Dynamic property detection and mapping
+   * - Attribute cleanup and removal
+   *
+   * @example
+   * // Install the plugin
+   * const app = new Eleva("myApp");
+   * app.use(AttrPlugin);
+   *
+   * // Use advanced attributes in components
+   * app.component("myComponent", {
+   *   template: (ctx) => `
+   *     <button
+   *       aria-expanded="${ctx.isExpanded.value}"
+   *       data-user-id="${ctx.userId.value}"
+   *       disabled="${ctx.isLoading.value}"
+   *       class="btn ${ctx.variant.value}"
+   *     >
+   *       ${ctx.text.value}
+   *     </button>
+   *   `
+   * });
+   */
+  const AttrPlugin = {
+    /**
+     * Unique identifier for the plugin
+     * @type {string}
+     */
+    name: "attr",
+    /**
+     * Plugin version
+     * @type {string}
+     */
+    version: "1.0.0-rc.10",
+    /**
+     * Plugin description
+     * @type {string}
+     */
+    description: "Advanced attribute handling for Eleva components",
+    /**
+     * Installs the plugin into the Eleva instance
+     *
+     * @param {Object} eleva - The Eleva instance
+     * @param {Object} options - Plugin configuration options
+     * @param {boolean} [options.enableAria=true] - Enable ARIA attribute handling
+     * @param {boolean} [options.enableData=true] - Enable data attribute handling
+     * @param {boolean} [options.enableBoolean=true] - Enable boolean attribute handling
+     * @param {boolean} [options.enableDynamic=true] - Enable dynamic property detection
+     */
+    install(eleva, options = {}) {
+      const {
+        enableAria = true,
+        enableData = true,
+        enableBoolean = true,
+        enableDynamic = true
+      } = options;
+
+      /**
+       * Updates the attributes of an element to match a new element's attributes.
+       * This method provides sophisticated attribute processing including:
+       * - ARIA attribute handling with proper property mapping
+       * - Data attribute management
+       * - Boolean attribute processing
+       * - Dynamic property detection and mapping
+       * - Attribute cleanup and removal
+       *
+       * @param {HTMLElement} oldEl - The original element to update
+       * @param {HTMLElement} newEl - The new element to update
+       * @returns {void}
+       */
+      const updateAttributes = (oldEl, newEl) => {
+        const oldAttrs = oldEl.attributes;
+        const newAttrs = newEl.attributes;
+
+        // Process new attributes
+        for (let i = 0; i < newAttrs.length; i++) {
+          const {
+            name,
+            value
+          } = newAttrs[i];
+
+          // Skip event attributes (handled by event system)
+          if (name.startsWith("@")) continue;
+
+          // Skip if attribute hasn't changed
+          if (oldEl.getAttribute(name) === value) continue;
+
+          // Handle ARIA attributes
+          if (enableAria && name.startsWith("aria-")) {
+            const prop = "aria" + name.slice(5).replace(CAMEL_RE, (_, l) => l.toUpperCase());
+            oldEl[prop] = value;
+            oldEl.setAttribute(name, value);
+          }
+          // Handle data attributes
+          else if (enableData && name.startsWith("data-")) {
+            oldEl.dataset[name.slice(5)] = value;
+            oldEl.setAttribute(name, value);
+          }
+          // Handle other attributes
+          else {
+            let prop = name.replace(CAMEL_RE, (_, l) => l.toUpperCase());
+
+            // Dynamic property detection
+            if (enableDynamic && !(prop in oldEl) && !Object.getOwnPropertyDescriptor(Object.getPrototypeOf(oldEl), prop)) {
+              const elementProps = Object.getOwnPropertyNames(Object.getPrototypeOf(oldEl));
+              const matchingProp = elementProps.find(p => p.toLowerCase() === name.toLowerCase() || p.toLowerCase().includes(name.toLowerCase()) || name.toLowerCase().includes(p.toLowerCase()));
+              if (matchingProp) {
+                prop = matchingProp;
+              }
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(oldEl), prop);
+            const hasProperty = prop in oldEl || descriptor;
+            if (hasProperty) {
+              // Boolean attribute handling
+              if (enableBoolean) {
+                const isBoolean = typeof oldEl[prop] === "boolean" || descriptor?.get && typeof descriptor.get.call(oldEl) === "boolean";
+                if (isBoolean) {
+                  const boolValue = value !== "false" && (value === "" || value === prop || value === "true");
+                  oldEl[prop] = boolValue;
+                  if (boolValue) {
+                    oldEl.setAttribute(name, "");
+                  } else {
+                    oldEl.removeAttribute(name);
+                  }
+                } else {
+                  oldEl[prop] = value;
+                  oldEl.setAttribute(name, value);
+                }
+              } else {
+                oldEl[prop] = value;
+                oldEl.setAttribute(name, value);
+              }
+            } else {
+              oldEl.setAttribute(name, value);
+            }
+          }
+        }
+
+        // Remove old attributes that are no longer present
+        for (let i = oldAttrs.length - 1; i >= 0; i--) {
+          const name = oldAttrs[i].name;
+          if (!newEl.hasAttribute(name)) {
+            oldEl.removeAttribute(name);
+          }
+        }
+      };
+
+      // Extend the renderer with the advanced attribute handler
+      if (eleva.renderer) {
+        eleva.renderer.updateAttributes = updateAttributes;
+
+        // Store the original _patchNode method
+        const originalPatchNode = eleva.renderer._patchNode;
+        eleva.renderer._originalPatchNode = originalPatchNode;
+
+        // Override the _patchNode method to use our attribute handler
+        eleva.renderer._patchNode = function (oldNode, newNode) {
+          if (oldNode?._eleva_instance) return;
+          if (!this._isSameNode(oldNode, newNode)) {
+            oldNode.replaceWith(newNode.cloneNode(true));
+            return;
+          }
+          if (oldNode.nodeType === Node.ELEMENT_NODE) {
+            updateAttributes(oldNode, newNode);
+            this._diff(oldNode, newNode);
+          } else if (oldNode.nodeType === Node.TEXT_NODE && oldNode.nodeValue !== newNode.nodeValue) {
+            oldNode.nodeValue = newNode.nodeValue;
+          }
+        };
+      }
+
+      // 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 attribute updates
+      eleva.updateElementAttributes = updateAttributes;
+    },
+    /**
+     * Uninstalls the plugin from the Eleva instance
+     *
+     * @param {Object} eleva - The Eleva instance
+     */
+    uninstall(eleva) {
+      // Restore original _patchNode method if it exists
+      if (eleva.renderer && eleva.renderer._originalPatchNode) {
+        eleva.renderer._patchNode = eleva.renderer._originalPatchNode;
+        delete eleva.renderer._originalPatchNode;
+      }
+
+      // Remove plugin metadata
+      if (eleva.plugins) {
+        eleva.plugins.delete(this.name);
+      }
+
+      // Remove utility methods
+      delete eleva.updateElementAttributes;
+    }
+  };
+
+  /**
+   * @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;
+    }
+  };
+
+  // ============================================================================
+  // TYPE DEFINITIONS - TypeScript-friendly JSDoc types for IDE support
+  // ============================================================================
+
+  /**
+   * @typedef {Record<string, unknown>} TemplateData
+   *           Data context for template interpolation
+   */
+
+  /**
+   * @typedef {string} TemplateString
+   *           A string containing {{ expression }} interpolation markers
+   */
+
+  /**
+   * @typedef {string} Expression
+   *           A JavaScript expression to be evaluated in the data context
+   */
+
+  /**
+   * @typedef {unknown} EvaluationResult
+   *           The result of evaluating an expression (string, number, boolean, object, etc.)
+   */
+
+  /**
+   * @class 🔒 TemplateEngine
+   * @classdesc A secure template engine that handles interpolation and dynamic attribute parsing.
+   * Provides a way to evaluate expressions in templates.
+   * All methods are static and can be called directly on the class.
+   *
+   * Template Syntax:
+   * - `{{ expression }}` - Interpolate any JavaScript expression
+   * - `{{ variable }}` - Access data properties directly
+   * - `{{ object.property }}` - Access nested properties
+   * - `{{ condition ? a : b }}` - Ternary expressions
+   * - `{{ func(arg) }}` - Call functions from data context
+   *
+   * @example
+   * // Basic interpolation
+   * const template = "Hello, {{name}}!";
+   * const data = { name: "World" };
+   * const result = TemplateEngine.parse(template, data);
+   * // Result: "Hello, World!"
+   *
+   * @example
+   * // Nested properties
+   * const template = "Welcome, {{user.name}}!";
+   * const data = { user: { name: "John" } };
+   * const result = TemplateEngine.parse(template, data);
+   * // Result: "Welcome, John!"
+   *
+   * @example
+   * // Expressions
+   * const template = "Status: {{active ? 'Online' : 'Offline'}}";
+   * const data = { active: true };
+   * const result = TemplateEngine.parse(template, data);
+   * // Result: "Status: Online"
+   *
+   * @example
+   * // With Signal values
+   * const template = "Count: {{count.value}}";
+   * const data = { count: { value: 42 } };
+   * const result = TemplateEngine.parse(template, data);
+   * // Result: "Count: 42"
+   */
+  class TemplateEngine {
+    /**
+     * Regular expression for matching template expressions in the format {{ expression }}
+     * Matches: {{ anything }} with optional whitespace inside braces
+     *
+     * @static
+     * @private
+     * @type {RegExp}
+     */
+    static expressionPattern = /\{\{\s*(.*?)\s*\}\}/g;
+
+    /**
+     * Parses a template string, replacing expressions with their evaluated values.
+     * Expressions are evaluated in the provided data context.
+     *
+     * @public
+     * @static
+     * @param {TemplateString|unknown} template - The template string to parse.
+     * @param {TemplateData} data - The data context for evaluating expressions.
+     * @returns {string} The parsed template with expressions replaced by their values.
+     *
+     * @example
+     * // Simple variables
+     * TemplateEngine.parse("Hello, {{name}}!", { name: "World" });
+     * // Result: "Hello, World!"
+     *
+     * @example
+     * // Nested properties
+     * TemplateEngine.parse("{{user.name}} is {{user.age}} years old", {
+     *   user: { name: "John", age: 30 }
+     * });
+     * // Result: "John is 30 years old"
+     *
+     * @example
+     * // Multiple expressions
+     * TemplateEngine.parse("{{greeting}}, {{name}}! You have {{count}} messages.", {
+     *   greeting: "Hello",
+     *   name: "User",
+     *   count: 5
+     * });
+     * // Result: "Hello, User! You have 5 messages."
+     *
+     * @example
+     * // With conditionals
+     * TemplateEngine.parse("Status: {{online ? 'Active' : 'Inactive'}}", {
+     *   online: true
+     * });
+     * // Result: "Status: Active"
+     */
+    static parse(template, data) {
+      if (typeof template !== "string") return template;
+      return template.replace(this.expressionPattern, (_, expression) => this.evaluate(expression, data));
+    }
+
+    /**
+     * Evaluates an expression in the context of the provided data object.
+     *
+     * Note: This does not provide a true sandbox and evaluated expressions may access global scope.
+     * The use of the `with` statement is necessary for expression evaluation but has security implications.
+     * Only use with trusted templates. User input should never be directly interpolated.
+     *
+     * @public
+     * @static
+     * @param {Expression|unknown} expression - The expression to evaluate.
+     * @param {TemplateData} data - The data context for evaluation.
+     * @returns {EvaluationResult} The result of the evaluation, or an empty string if evaluation fails.
+     *
+     * @example
+     * // Property access
+     * TemplateEngine.evaluate("user.name", { user: { name: "John" } });
+     * // Result: "John"
+     *
+     * @example
+     * // Numeric values
+     * TemplateEngine.evaluate("user.age", { user: { age: 30 } });
+     * // Result: 30
+     *
+     * @example
+     * // Expressions
+     * TemplateEngine.evaluate("items.length > 0", { items: [1, 2, 3] });
+     * // Result: true
+     *
+     * @example
+     * // Function calls
+     * TemplateEngine.evaluate("formatDate(date)", {
+     *   date: new Date(),
+     *   formatDate: (d) => d.toISOString()
+     * });
+     * // Result: "2024-01-01T00:00:00.000Z"
+     *
+     * @example
+     * // Failed evaluation returns empty string
+     * TemplateEngine.evaluate("nonexistent.property", {});
+     * // Result: ""
+     */
+    static evaluate(expression, data) {
+      if (typeof expression !== "string") return expression;
+      try {
+        return new Function("data", `with(data) { return ${expression}; }`)(data);
+      } catch {
+        return "";
+      }
+    }
+  }
+
+  /**
+   * @class 🎯 PropsPlugin
+   * @classdesc A plugin that extends Eleva's props data handling to support any type of data structure
+   * with automatic type detection, parsing, and reactive prop updates. This plugin enables seamless
+   * passing of complex data types from parent to child components without manual parsing.
+   *
+   * Core Features:
+   * - Automatic type detection and parsing (strings, numbers, booleans, objects, arrays, dates, etc.)
+   * - Support for complex data structures including nested objects and arrays
+   * - Reactive props that automatically update when parent data changes
+   * - Comprehensive error handling with custom error callbacks
+   * - Simple configuration with minimal setup required
+   *
+   * @example
+   * // Install the plugin
+   * const app = new Eleva("myApp");
+   * app.use(PropsPlugin, {
+   *   enableAutoParsing: true,
+   *   enableReactivity: true,
+   *   onError: (error, value) => {
+   *     console.error('Props parsing error:', error, value);
+   *   }
+   * });
+   *
+   * // Use complex props in components
+   * app.component("UserCard", {
+   *   template: (ctx) => `
+   *     <div class="user-info-container"
+   *          :user='${JSON.stringify(ctx.user.value)}'
+   *          :permissions='${JSON.stringify(ctx.permissions.value)}'
+   *          :settings='${JSON.stringify(ctx.settings.value)}'>
+   *     </div>
+   *   `,
+   *   children: {
+   *     '.user-info-container': 'UserInfo'
+   *   }
+   * });
+   *
+   * app.component("UserInfo", {
+   *   setup({ props }) {
+   *     return {
+   *       user: props.user,        // Automatically parsed object
+   *       permissions: props.permissions,  // Automatically parsed array
+   *       settings: props.settings  // Automatically parsed object
+   *     };
+   *   }
+   * });
+   */
+  const PropsPlugin = {
+    /**
+     * Unique identifier for the plugin
+     * @type {string}
+     */
+    name: "props",
+    /**
+     * Plugin version
+     * @type {string}
+     */
+    version: "1.0.0-rc.10",
+    /**
+     * Plugin description
+     * @type {string}
+     */
+    description: "Advanced props data handling for complex data structures with automatic type detection and reactivity",
+    /**
+     * Installs the plugin into the Eleva instance
+     *
+     * @param {Object} eleva - The Eleva instance
+     * @param {Object} options - Plugin configuration options
+     * @param {boolean} [options.enableAutoParsing=true] - Enable automatic type detection and parsing
+     * @param {boolean} [options.enableReactivity=true] - Enable reactive prop updates using Eleva's signal system
+     * @param {Function} [options.onError=null] - Error handler function called when parsing fails
+     *
+     * @example
+     * // Basic installation
+     * app.use(PropsPlugin);
+     *
+     * // Installation with custom options
+     * app.use(PropsPlugin, {
+     *   enableAutoParsing: true,
+     *   enableReactivity: false,
+     *   onError: (error, value) => {
+     *     console.error('Props parsing error:', error, value);
+     *   }
+     * });
+     */
+    install(eleva, options = {}) {
+      const {
+        enableAutoParsing = true,
+        enableReactivity = true,
+        onError = null
+      } = options;
+
+      /**
+       * Detects the type of a given value
+       * @private
+       * @param {any} value - The value to detect type for
+       * @returns {string} The detected type ('string', 'number', 'boolean', 'object', 'array', 'date', 'map', 'set', 'function', 'null', 'undefined', 'unknown')
+       *
+       * @example
+       * detectType("hello")     // → "string"
+       * detectType(42)          // → "number"
+       * detectType(true)        // → "boolean"
+       * detectType([1, 2, 3])   // → "array"
+       * detectType({})          // → "object"
+       * detectType(new Date())  // → "date"
+       * detectType(null)        // → "null"
+       */
+      const detectType = value => {
+        if (value === null) return "null";
+        if (value === undefined) return "undefined";
+        if (typeof value === "boolean") return "boolean";
+        if (typeof value === "number") return "number";
+        if (typeof value === "string") return "string";
+        if (typeof value === "function") return "function";
+        if (value instanceof Date) return "date";
+        if (value instanceof Map) return "map";
+        if (value instanceof Set) return "set";
+        if (Array.isArray(value)) return "array";
+        if (typeof value === "object") return "object";
+        return "unknown";
+      };
+
+      /**
+       * Parses a prop value with automatic type detection
+       * @private
+       * @param {any} value - The value to parse
+       * @returns {any} The parsed value with appropriate type
+       *
+       * @description
+       * This function automatically detects and parses different data types from string values:
+       * - Special strings: "true" → true, "false" → false, "null" → null, "undefined" → undefined
+       * - JSON objects/arrays: '{"key": "value"}' → {key: "value"}, '[1, 2, 3]' → [1, 2, 3]
+       * - Boolean-like strings: "1" → true, "0" → false, "" → true
+       * - Numeric strings: "42" → 42, "3.14" → 3.14
+       * - Date strings: "2023-01-01T00:00:00.000Z" → Date object
+       * - Other strings: returned as-is
+       *
+       * @example
+       * parsePropValue("true")           // → true
+       * parsePropValue("42")             // → 42
+       * parsePropValue('{"key": "val"}') // → {key: "val"}
+       * parsePropValue('[1, 2, 3]')      // → [1, 2, 3]
+       * parsePropValue("hello")          // → "hello"
+       */
+      const parsePropValue = value => {
+        try {
+          // Handle non-string values - return as-is
+          if (typeof value !== "string") {
+            return value;
+          }
+
+          // Handle special string patterns first
+          if (value === "true") return true;
+          if (value === "false") return false;
+          if (value === "null") return null;
+          if (value === "undefined") return undefined;
+
+          // Try to parse as JSON (for objects and arrays)
+          // This handles complex data structures like objects and arrays
+          if (value.startsWith("{") || value.startsWith("[")) {
+            try {
+              return JSON.parse(value);
+            } catch (e) {
+              // Not valid JSON, throw error to trigger error handler
+              throw new Error(`Invalid JSON: ${value}`);
+            }
+          }
+
+          // Handle boolean-like strings (including "1" and "0")
+          // These are common in HTML attributes and should be treated as booleans
+          if (value === "1") return true;
+          if (value === "0") return false;
+          if (value === "") return true; // Empty string is truthy in HTML attributes
+
+          // Handle numeric strings (after boolean check to avoid conflicts)
+          // This ensures "0" is treated as boolean false, not number 0
+          if (!isNaN(value) && value !== "" && !isNaN(parseFloat(value))) {
+            return Number(value);
+          }
+
+          // Handle date strings (ISO format)
+          // Recognizes standard ISO date format and converts to Date object
+          if (value.match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/)) {
+            const date = new Date(value);
+            if (!isNaN(date.getTime())) {
+              return date;
+            }
+          }
+
+          // Return as string if no other parsing applies
+          // This is the fallback for regular text strings
+          return value;
+        } catch (error) {
+          // Call error handler if provided
+          if (onError) {
+            onError(error, value);
+          }
+          // Fallback to original value to prevent breaking the application
+          return value;
+        }
+      };
+
+      /**
+       * Enhanced props extraction with automatic type detection
+       * @private
+       * @param {HTMLElement} element - The DOM element to extract props from
+       * @returns {Object} Object containing parsed props with appropriate types
+       *
+       * @description
+       * Extracts props from DOM element attributes that start with ":" and automatically
+       * parses them to their appropriate types. Removes the attributes from the element
+       * after extraction.
+       *
+       * @example
+       * // HTML: <div :name="John" :age="30" :active="true" :data='{"key": "value"}'></div>
+       * const props = extractProps(element);
+       * // Result: { name: "John", age: 30, active: true, data: {key: "value"} }
+       */
+      const extractProps = element => {
+        const props = {};
+        const attrs = element.attributes;
+
+        // Iterate through attributes in reverse order to handle removal correctly
+        for (let i = attrs.length - 1; i >= 0; i--) {
+          const attr = attrs[i];
+          // Only process attributes that start with ":" (prop attributes)
+          if (attr.name.startsWith(":")) {
+            const propName = attr.name.slice(1); // Remove the ":" prefix
+            // Parse the value if auto-parsing is enabled, otherwise use as-is
+            const parsedValue = enableAutoParsing ? parsePropValue(attr.value) : attr.value;
+            props[propName] = parsedValue;
+            // Remove the attribute from the DOM element after extraction
+            element.removeAttribute(attr.name);
+          }
+        }
+        return props;
+      };
+
+      /**
+       * Creates reactive props using Eleva's signal system
+       * @private
+       * @param {Object} props - The props object to make reactive
+       * @returns {Object} Object containing reactive props (Eleva signals)
+       *
+       * @description
+       * Converts regular prop values into Eleva signals for reactive updates.
+       * If a value is already a signal, it's passed through unchanged.
+       *
+       * @example
+       * const props = { name: "John", age: 30, active: true };
+       * const reactiveProps = createReactiveProps(props);
+       * // Result: {
+       * //   name: Signal("John"),
+       * //   age: Signal(30),
+       * //   active: Signal(true)
+       * // }
+       */
+      const createReactiveProps = props => {
+        const reactiveProps = {};
+
+        // Convert each prop value to a reactive signal
+        Object.entries(props).forEach(([key, value]) => {
+          // Check if value is already a signal (has 'value' and 'watch' properties)
+          if (value && typeof value === "object" && "value" in value && "watch" in value) {
+            // Value is already a signal, use it as-is
+            reactiveProps[key] = value;
+          } else {
+            // Create new signal for the prop value to make it reactive
+            reactiveProps[key] = new eleva.signal(value);
+          }
+        });
+        return reactiveProps;
+      };
+
+      // Override Eleva's internal _extractProps method with our enhanced version
+      eleva._extractProps = extractProps;
+
+      // Override Eleva's mount method to apply enhanced prop handling
+      const originalMount = eleva.mount;
+      eleva.mount = async (container, compName, props = {}) => {
+        // Create reactive props if reactivity is enabled
+        const enhancedProps = enableReactivity ? createReactiveProps(props) : props;
+
+        // Call the original mount method with enhanced props
+        return await originalMount.call(eleva, container, compName, enhancedProps);
+      };
+
+      // Override Eleva's _mountComponents method to enable signal reference passing
+      const originalMountComponents = eleva._mountComponents;
+
+      // Cache to store parent contexts by container element
+      const parentContextCache = new WeakMap();
+      // Store child instances that need signal linking
+      const pendingSignalLinks = new Set();
+      eleva._mountComponents = async (container, children, childInstances) => {
+        for (const [selector, component] of Object.entries(children)) {
+          if (!selector) continue;
+          for (const el of container.querySelectorAll(selector)) {
+            if (!(el instanceof HTMLElement)) continue;
+
+            // Extract props from DOM attributes
+            const extractedProps = eleva._extractProps(el);
+
+            // Get parent context to check for signal references
+            let enhancedProps = extractedProps;
+
+            // Try to find parent context by looking up the DOM tree
+            let parentContext = parentContextCache.get(container);
+            if (!parentContext) {
+              let currentElement = container;
+              while (currentElement && !parentContext) {
+                if (currentElement._eleva_instance && currentElement._eleva_instance.data) {
+                  parentContext = currentElement._eleva_instance.data;
+                  // Cache the parent context for future use
+                  parentContextCache.set(container, parentContext);
+                  break;
+                }
+                currentElement = currentElement.parentElement;
+              }
+            }
+            if (enableReactivity && parentContext) {
+              const signalProps = {};
+
+              // Check each extracted prop to see if there's a matching signal in parent context
+              Object.keys(extractedProps).forEach(propName => {
+                if (parentContext[propName] && parentContext[propName] instanceof eleva.signal) {
+                  // Found a signal in parent context with the same name as the prop
+                  // Pass the signal reference instead of creating a new one
+                  signalProps[propName] = parentContext[propName];
+                }
+              });
+
+              // Merge signal props with regular props (signal props take precedence)
+              enhancedProps = {
+                ...extractedProps,
+                ...signalProps
+              };
+            }
+
+            // Create reactive props for non-signal props only
+            let finalProps = enhancedProps;
+            if (enableReactivity) {
+              // Only create reactive props for values that aren't already signals
+              const nonSignalProps = {};
+              Object.entries(enhancedProps).forEach(([key, value]) => {
+                if (!(value && typeof value === "object" && "value" in value && "watch" in value)) {
+                  // This is not a signal, create a reactive prop for it
+                  nonSignalProps[key] = value;
+                }
+              });
+
+              // Create reactive props only for non-signal values
+              const reactiveNonSignalProps = createReactiveProps(nonSignalProps);
+
+              // Merge signal props with reactive non-signal props
+              finalProps = {
+                ...reactiveNonSignalProps,
+                ...enhancedProps // Signal props take precedence
+              };
+            }
+
+            /** @type {MountResult} */
+            const instance = await eleva.mount(el, component, finalProps);
+            if (instance && !childInstances.includes(instance)) {
+              childInstances.push(instance);
+
+              // If we have extracted props but no parent context yet, mark for later signal linking
+              if (enableReactivity && Object.keys(extractedProps).length > 0 && !parentContext) {
+                pendingSignalLinks.add({
+                  instance,
+                  extractedProps,
+                  container,
+                  component
+                });
+              }
+            }
+          }
+        }
+
+        // After mounting all children, try to link signals for pending instances
+        if (enableReactivity && pendingSignalLinks.size > 0) {
+          for (const pending of pendingSignalLinks) {
+            const {
+              instance,
+              extractedProps,
+              container,
+              component
+            } = pending;
+
+            // Try to find parent context again
+            let parentContext = parentContextCache.get(container);
+            if (!parentContext) {
+              let currentElement = container;
+              while (currentElement && !parentContext) {
+                if (currentElement._eleva_instance && currentElement._eleva_instance.data) {
+                  parentContext = currentElement._eleva_instance.data;
+                  parentContextCache.set(container, parentContext);
+                  break;
+                }
+                currentElement = currentElement.parentElement;
+              }
+            }
+            if (parentContext) {
+              const signalProps = {};
+
+              // Check each extracted prop to see if there's a matching signal in parent context
+              Object.keys(extractedProps).forEach(propName => {
+                if (parentContext[propName] && parentContext[propName] instanceof eleva.signal) {
+                  signalProps[propName] = parentContext[propName];
+                }
+              });
+
+              // Update the child instance's data with signal references
+              if (Object.keys(signalProps).length > 0) {
+                Object.assign(instance.data, signalProps);
+
+                // Set up signal watchers for the newly linked signals
+                Object.keys(signalProps).forEach(propName => {
+                  const signal = signalProps[propName];
+                  if (signal && typeof signal.watch === "function") {
+                    signal.watch(newValue => {
+                      // Trigger a re-render of the child component when the signal changes
+                      const childComponent = eleva._components.get(component) || component;
+                      if (childComponent && childComponent.template) {
+                        const templateResult = typeof childComponent.template === "function" ? childComponent.template(instance.data) : childComponent.template;
+                        const newHtml = TemplateEngine.parse(templateResult, instance.data);
+                        eleva.renderer.patchDOM(instance.container, newHtml);
+                      }
+                    });
+                  }
+                });
+
+                // Initial re-render to show the correct signal values
+                const childComponent = eleva._components.get(component) || component;
+                if (childComponent && childComponent.template) {
+                  const templateResult = typeof childComponent.template === "function" ? childComponent.template(instance.data) : childComponent.template;
+                  const newHtml = TemplateEngine.parse(templateResult, instance.data);
+                  eleva.renderer.patchDOM(instance.container, newHtml);
+                }
+              }
+
+              // Remove from pending list
+              pendingSignalLinks.delete(pending);
+            }
+          }
+        }
+      };
+
+      /**
+       * Expose utility methods on the Eleva instance
+       * @namespace eleva.props
+       */
+      eleva.props = {
+        /**
+         * Parse a single value with automatic type detection
+         * @param {any} value - The value to parse
+         * @returns {any} The parsed value with appropriate type
+         *
+         * @example
+         * app.props.parse("42")             // → 42
+         * app.props.parse("true")           // → true
+         * app.props.parse('{"key": "val"}') // → {key: "val"}
+         */
+        parse: value => {
+          // Return value as-is if auto parsing is disabled
+          if (!enableAutoParsing) {
+            return value;
+          }
+          // Use our enhanced parsing function
+          return parsePropValue(value);
+        },
+        /**
+         * Detect the type of a value
+         * @param {any} value - The value to detect type for
+         * @returns {string} The detected type
+         *
+         * @example
+         * app.props.detectType("hello")     // → "string"
+         * app.props.detectType(42)          // → "number"
+         * app.props.detectType([1, 2, 3])   // → "array"
+         */
+        detectType
+      };
+
+      // Store original methods for uninstall
+      eleva._originalExtractProps = eleva._extractProps;
+      eleva._originalMount = originalMount;
+      eleva._originalMountComponents = originalMountComponents;
+    },
+    /**
+     * Uninstalls the plugin from the Eleva instance
+     *
+     * @param {Object} eleva - The Eleva instance
+     *
+     * @description
+     * Restores the original Eleva methods and removes all plugin-specific
+     * functionality. This method should be called when the plugin is no
+     * longer needed.
+     *
+     * @example
+     * // Uninstall the plugin
+     * PropsPlugin.uninstall(app);
+     */
+    uninstall(eleva) {
+      // Restore original _extractProps method
+      if (eleva._originalExtractProps) {
+        eleva._extractProps = eleva._originalExtractProps;
+        delete eleva._originalExtractProps;
+      }
+
+      // Restore original mount method
+      if (eleva._originalMount) {
+        eleva.mount = eleva._originalMount;
+        delete eleva._originalMount;
+      }
+
+      // Restore original _mountComponents method
+      if (eleva._originalMountComponents) {
+        eleva._mountComponents = eleva._originalMountComponents;
+        delete eleva._originalMountComponents;
+      }
+
+      // Remove plugin utility methods
+      if (eleva.props) {
+        delete eleva.props;
+      }
+    }
+  };
+
+  /**
+   * @class 🏪 StorePlugin
+   * @classdesc A powerful reactive state management plugin for Eleva.js that enables sharing
+   * reactive data across the entire application. The Store plugin provides a centralized,
+   * reactive data store that can be accessed from any component's setup function.
+   *
+   * Core Features:
+   * - Centralized reactive state management using Eleva's signal system
+   * - Global state accessibility through component setup functions
+   * - Namespace support for organizing store modules
+   * - Built-in persistence with localStorage/sessionStorage support
+   * - Action-based state mutations with validation
+   * - Subscription system for reactive updates
+   * - DevTools integration for debugging
+   * - Plugin architecture for extensibility
+   *
+   * @example
+   * // Install the plugin
+   * const app = new Eleva("myApp");
+   * app.use(StorePlugin, {
+   *   state: {
+   *     user: { name: "John", email: "john@example.com" },
+   *     counter: 0,
+   *     todos: []
+   *   },
+   *   actions: {
+   *     increment: (state) => state.counter.value++,
+   *     addTodo: (state, todo) => state.todos.value.push(todo),
+   *     setUser: (state, user) => state.user.value = user
+   *   },
+   *   persistence: {
+   *     enabled: true,
+   *     key: "myApp-store",
+   *     storage: "localStorage"
+   *   }
+   * });
+   *
+   * // Use store in components
+   * app.component("Counter", {
+   *   setup({ store }) {
+   *     return {
+   *       count: store.state.counter,
+   *       increment: () => store.dispatch("increment"),
+   *       user: store.state.user
+   *     };
+   *   },
+   *   template: (ctx) => `
+   *     <div>
+   *       <p>Hello ${ctx.user.value.name}!</p>
+   *       <p>Count: ${ctx.count.value}</p>
+   *       <button onclick="ctx.increment()">+</button>
+   *     </div>
+   *   `
+   * });
+   */
+  const StorePlugin = {
+    /**
+     * Unique identifier for the plugin
+     * @type {string}
+     */
+    name: "store",
+    /**
+     * Plugin version
+     * @type {string}
+     */
+    version: "1.0.0-rc.10",
+    /**
+     * Plugin description
+     * @type {string}
+     */
+    description: "Reactive state management for sharing data across the entire Eleva application",
+    /**
+     * Installs the plugin into the Eleva instance
+     *
+     * @param {Object} eleva - The Eleva instance
+     * @param {Object} options - Plugin configuration options
+     * @param {Object} [options.state={}] - Initial state object
+     * @param {Object} [options.actions={}] - Action functions for state mutations
+     * @param {Object} [options.namespaces={}] - Namespaced modules for organizing store
+     * @param {Object} [options.persistence] - Persistence configuration
+     * @param {boolean} [options.persistence.enabled=false] - Enable state persistence
+     * @param {string} [options.persistence.key="eleva-store"] - Storage key
+     * @param {"localStorage" | "sessionStorage"} [options.persistence.storage="localStorage"] - Storage type
+     * @param {Array<string>} [options.persistence.include] - State keys to persist (if not provided, all state is persisted)
+     * @param {Array<string>} [options.persistence.exclude] - State keys to exclude from persistence
+     * @param {boolean} [options.devTools=false] - Enable development tools integration
+     * @param {Function} [options.onError=null] - Error handler function
+     *
+     * @example
+     * // Basic installation
+     * app.use(StorePlugin, {
+     *   state: { count: 0, user: null },
+     *   actions: {
+     *     increment: (state) => state.count.value++,
+     *     setUser: (state, user) => state.user.value = user
+     *   }
+     * });
+     *
+     * // Advanced installation with persistence and namespaces
+     * app.use(StorePlugin, {
+     *   state: { theme: "light" },
+     *   namespaces: {
+     *     auth: {
+     *       state: { user: null, token: null },
+     *       actions: {
+     *         login: (state, { user, token }) => {
+     *           state.user.value = user;
+     *           state.token.value = token;
+     *         },
+     *         logout: (state) => {
+     *           state.user.value = null;
+     *           state.token.value = null;
+     *         }
+     *       }
+     *     }
+     *   },
+     *   persistence: {
+     *     enabled: true,
+     *     include: ["theme", "auth.user"]
+     *   }
+     * });
+     */
+    install(eleva, options = {}) {
+      const {
+        state = {},
+        actions = {},
+        namespaces = {},
+        persistence = {},
+        devTools = false,
+        onError = null
+      } = options;
+
+      /**
+       * Store instance that manages all state and provides the API
+       * @private
+       */
+      class Store {
+        constructor() {
+          this.state = {};
+          this.actions = {};
+          this.subscribers = new Set();
+          this.mutations = [];
+          this.persistence = {
+            enabled: false,
+            key: "eleva-store",
+            storage: "localStorage",
+            include: null,
+            exclude: null,
+            ...persistence
+          };
+          this.devTools = devTools;
+          this.onError = onError;
+          this._initializeState(state, actions);
+          this._initializeNamespaces(namespaces);
+          this._loadPersistedState();
+          this._setupDevTools();
+        }
+
+        /**
+         * Initializes the root state and actions
+         * @private
+         */
+        _initializeState(initialState, initialActions) {
+          // Create reactive signals for each state property
+          Object.entries(initialState).forEach(([key, value]) => {
+            this.state[key] = new eleva.signal(value);
+          });
+
+          // Set up actions
+          this.actions = {
+            ...initialActions
+          };
+        }
+
+        /**
+         * Initializes namespaced modules
+         * @private
+         */
+        _initializeNamespaces(namespaces) {
+          Object.entries(namespaces).forEach(([namespace, module]) => {
+            const {
+              state: moduleState = {},
+              actions: moduleActions = {}
+            } = module;
+
+            // Create namespace object if it doesn't exist
+            if (!this.state[namespace]) {
+              this.state[namespace] = {};
+            }
+            if (!this.actions[namespace]) {
+              this.actions[namespace] = {};
+            }
+
+            // Initialize namespaced state
+            Object.entries(moduleState).forEach(([key, value]) => {
+              this.state[namespace][key] = new eleva.signal(value);
+            });
+
+            // Set up namespaced actions
+            this.actions[namespace] = {
+              ...moduleActions
+            };
+          });
+        }
+
+        /**
+         * Loads persisted state from storage
+         * @private
+         */
+        _loadPersistedState() {
+          if (!this.persistence.enabled || typeof window === "undefined") {
+            return;
+          }
+          try {
+            const storage = window[this.persistence.storage];
+            const persistedData = storage.getItem(this.persistence.key);
+            if (persistedData) {
+              const data = JSON.parse(persistedData);
+              this._applyPersistedData(data);
+            }
+          } catch (error) {
+            if (this.onError) {
+              this.onError(error, "Failed to load persisted state");
+            } else {
+              console.warn("[StorePlugin] Failed to load persisted state:", error);
+            }
+          }
+        }
+
+        /**
+         * Applies persisted data to the current state
+         * @private
+         */
+        _applyPersistedData(data, currentState = this.state, path = "") {
+          Object.entries(data).forEach(([key, value]) => {
+            const fullPath = path ? `${path}.${key}` : key;
+            if (this._shouldPersist(fullPath)) {
+              if (currentState[key] && typeof currentState[key] === "object" && "value" in currentState[key]) {
+                // This is a signal, update its value
+                currentState[key].value = value;
+              } else if (typeof value === "object" && value !== null && currentState[key]) {
+                // This is a nested object, recurse
+                this._applyPersistedData(value, currentState[key], fullPath);
+              }
+            }
+          });
+        }
+
+        /**
+         * Determines if a state path should be persisted
+         * @private
+         */
+        _shouldPersist(path) {
+          const {
+            include,
+            exclude
+          } = this.persistence;
+          if (include && include.length > 0) {
+            return include.some(includePath => path.startsWith(includePath));
+          }
+          if (exclude && exclude.length > 0) {
+            return !exclude.some(excludePath => path.startsWith(excludePath));
+          }
+          return true;
+        }
+
+        /**
+         * Saves current state to storage
+         * @private
+         */
+        _saveState() {
+          if (!this.persistence.enabled || typeof window === "undefined") {
+            return;
+          }
+          try {
+            const storage = window[this.persistence.storage];
+            const dataToSave = this._extractPersistedData();
+            storage.setItem(this.persistence.key, JSON.stringify(dataToSave));
+          } catch (error) {
+            if (this.onError) {
+              this.onError(error, "Failed to save state");
+            } else {
+              console.warn("[StorePlugin] Failed to save state:", error);
+            }
+          }
+        }
+
+        /**
+         * Extracts data that should be persisted
+         * @private
+         */
+        _extractPersistedData(currentState = this.state, path = "") {
+          const result = {};
+          Object.entries(currentState).forEach(([key, value]) => {
+            const fullPath = path ? `${path}.${key}` : key;
+            if (this._shouldPersist(fullPath)) {
+              if (value && typeof value === "object" && "value" in value) {
+                // This is a signal, extract its value
+                result[key] = value.value;
+              } else if (typeof value === "object" && value !== null) {
+                // This is a nested object, recurse
+                const nestedData = this._extractPersistedData(value, fullPath);
+                if (Object.keys(nestedData).length > 0) {
+                  result[key] = nestedData;
+                }
+              }
+            }
+          });
+          return result;
+        }
+
+        /**
+         * Sets up development tools integration
+         * @private
+         */
+        _setupDevTools() {
+          if (!this.devTools || typeof window === "undefined" || !window.__ELEVA_DEVTOOLS__) {
+            return;
+          }
+          window.__ELEVA_DEVTOOLS__.registerStore(this);
+        }
+
+        /**
+         * Dispatches an action to mutate the state
+         * @param {string} actionName - The name of the action to dispatch (supports namespaced actions like "auth.login")
+         * @param {any} payload - The payload to pass to the action
+         * @returns {Promise<any>} The result of the action
+         */
+        async dispatch(actionName, payload) {
+          try {
+            const action = this._getAction(actionName);
+            if (!action) {
+              const error = new Error(`Action "${actionName}" not found`);
+              if (this.onError) {
+                this.onError(error, actionName);
+              }
+              throw error;
+            }
+            const mutation = {
+              type: actionName,
+              payload,
+              timestamp: Date.now()
+            };
+
+            // Record mutation for devtools
+            this.mutations.push(mutation);
+            if (this.mutations.length > 100) {
+              this.mutations.shift(); // Keep only last 100 mutations
+            }
+
+            // Execute the action
+            const result = await action.call(null, this.state, payload);
+
+            // Save state if persistence is enabled
+            this._saveState();
+
+            // Notify subscribers
+            this.subscribers.forEach(callback => {
+              try {
+                callback(mutation, this.state);
+              } catch (error) {
+                if (this.onError) {
+                  this.onError(error, "Subscriber callback failed");
+                }
+              }
+            });
+
+            // Notify devtools
+            if (this.devTools && typeof window !== "undefined" && window.__ELEVA_DEVTOOLS__) {
+              window.__ELEVA_DEVTOOLS__.notifyMutation(mutation, this.state);
+            }
+            return result;
+          } catch (error) {
+            if (this.onError) {
+              this.onError(error, `Action dispatch failed: ${actionName}`);
+            }
+            throw error;
+          }
+        }
+
+        /**
+         * Gets an action by name (supports namespaced actions)
+         * @private
+         */
+        _getAction(actionName) {
+          const parts = actionName.split(".");
+          let current = this.actions;
+          for (const part of parts) {
+            if (current[part] === undefined) {
+              return null;
+            }
+            current = current[part];
+          }
+          return typeof current === "function" ? current : null;
+        }
+
+        /**
+         * Subscribes to store mutations
+         * @param {Function} callback - Callback function to call on mutations
+         * @returns {Function} Unsubscribe function
+         */
+        subscribe(callback) {
+          if (typeof callback !== "function") {
+            throw new Error("Subscribe callback must be a function");
+          }
+          this.subscribers.add(callback);
+
+          // Return unsubscribe function
+          return () => {
+            this.subscribers.delete(callback);
+          };
+        }
+
+        /**
+         * Gets a deep copy of the current state values (not signals)
+         * @returns {Object} The current state values
+         */
+        getState() {
+          return this._extractPersistedData();
+        }
+
+        /**
+         * Replaces the entire state (useful for testing or state hydration)
+         * @param {Object} newState - The new state object
+         */
+        replaceState(newState) {
+          this._applyPersistedData(newState);
+          this._saveState();
+        }
+
+        /**
+         * Clears persisted state from storage
+         */
+        clearPersistedState() {
+          if (!this.persistence.enabled || typeof window === "undefined") {
+            return;
+          }
+          try {
+            const storage = window[this.persistence.storage];
+            storage.removeItem(this.persistence.key);
+          } catch (error) {
+            if (this.onError) {
+              this.onError(error, "Failed to clear persisted state");
+            }
+          }
+        }
+
+        /**
+         * Registers a new namespaced module at runtime
+         * @param {string} namespace - The namespace for the module
+         * @param {Object} module - The module definition
+         * @param {Object} module.state - The module's initial state
+         * @param {Object} module.actions - The module's actions
+         */
+        registerModule(namespace, module) {
+          if (this.state[namespace] || this.actions[namespace]) {
+            console.warn(`[StorePlugin] Module "${namespace}" already exists`);
+            return;
+          }
+
+          // Initialize the module
+          this.state[namespace] = {};
+          this.actions[namespace] = {};
+          const namespaces = {
+            [namespace]: module
+          };
+          this._initializeNamespaces(namespaces);
+          this._saveState();
+        }
+
+        /**
+         * Unregisters a namespaced module
+         * @param {string} namespace - The namespace to unregister
+         */
+        unregisterModule(namespace) {
+          if (!this.state[namespace] && !this.actions[namespace]) {
+            console.warn(`[StorePlugin] Module "${namespace}" does not exist`);
+            return;
+          }
+          delete this.state[namespace];
+          delete this.actions[namespace];
+          this._saveState();
+        }
+
+        /**
+         * Creates a new reactive state property at runtime
+         * @param {string} key - The state key
+         * @param {*} initialValue - The initial value
+         * @returns {Object} The created signal
+         */
+        createState(key, initialValue) {
+          if (this.state[key]) {
+            return this.state[key]; // Return existing state
+          }
+          this.state[key] = new eleva.signal(initialValue);
+          this._saveState();
+          return this.state[key];
+        }
+
+        /**
+         * Creates a new action at runtime
+         * @param {string} name - The action name
+         * @param {Function} actionFn - The action function
+         */
+        createAction(name, actionFn) {
+          if (typeof actionFn !== "function") {
+            throw new Error("Action must be a function");
+          }
+          this.actions[name] = actionFn;
+        }
+      }
+
+      // Create the store instance
+      const store = new Store();
+
+      // Store the original mount method to override it
+      const originalMount = eleva.mount;
+
+      /**
+       * Override the mount method to inject store context into components
+       */
+      eleva.mount = async (container, compName, props = {}) => {
+        // Get the component definition
+        const componentDef = typeof compName === "string" ? eleva._components.get(compName) || compName : compName;
+        if (!componentDef) {
+          return await originalMount.call(eleva, container, compName, props);
+        }
+
+        // Create a wrapped component that injects store into setup
+        const wrappedComponent = {
+          ...componentDef,
+          async setup(ctx) {
+            // Inject store into the context with enhanced API
+            ctx.store = {
+              // Core store functionality
+              state: store.state,
+              dispatch: store.dispatch.bind(store),
+              subscribe: store.subscribe.bind(store),
+              getState: store.getState.bind(store),
+              // Module management
+              registerModule: store.registerModule.bind(store),
+              unregisterModule: store.unregisterModule.bind(store),
+              // Utilities for dynamic state/action creation
+              createState: store.createState.bind(store),
+              createAction: store.createAction.bind(store),
+              // Access to signal constructor for manual state creation
+              signal: eleva.signal
+            };
+
+            // Call original setup if it exists
+            const originalSetup = componentDef.setup;
+            const result = originalSetup ? await originalSetup(ctx) : {};
+            return result;
+          }
+        };
+
+        // Call original mount with wrapped component
+        return await originalMount.call(eleva, container, wrappedComponent, props);
+      };
+
+      // Override _mountComponents to ensure child components also get store context
+      const originalMountComponents = eleva._mountComponents;
+      eleva._mountComponents = async (container, children, childInstances) => {
+        // Create wrapped children with store injection
+        const wrappedChildren = {};
+        for (const [selector, childComponent] of Object.entries(children)) {
+          const componentDef = typeof childComponent === "string" ? eleva._components.get(childComponent) || childComponent : childComponent;
+          if (componentDef && typeof componentDef === "object") {
+            wrappedChildren[selector] = {
+              ...componentDef,
+              async setup(ctx) {
+                // Inject store into the context with enhanced API
+                ctx.store = {
+                  // Core store functionality
+                  state: store.state,
+                  dispatch: store.dispatch.bind(store),
+                  subscribe: store.subscribe.bind(store),
+                  getState: store.getState.bind(store),
+                  // Module management
+                  registerModule: store.registerModule.bind(store),
+                  unregisterModule: store.unregisterModule.bind(store),
+                  // Utilities for dynamic state/action creation
+                  createState: store.createState.bind(store),
+                  createAction: store.createAction.bind(store),
+                  // Access to signal constructor for manual state creation
+                  signal: eleva.signal
+                };
+
+                // Call original setup if it exists
+                const originalSetup = componentDef.setup;
+                const result = originalSetup ? await originalSetup(ctx) : {};
+                return result;
+              }
+            };
+          } else {
+            wrappedChildren[selector] = childComponent;
+          }
+        }
+
+        // Call original _mountComponents with wrapped children
+        return await originalMountComponents.call(eleva, container, wrappedChildren, childInstances);
+      };
+
+      // Expose store instance and utilities on the Eleva instance
+      eleva.store = store;
+
+      /**
+       * Expose utility methods on the Eleva instance
+       * @namespace eleva.store
+       */
+      eleva.createAction = (name, actionFn) => {
+        store.actions[name] = actionFn;
+      };
+      eleva.dispatch = (actionName, payload) => {
+        return store.dispatch(actionName, payload);
+      };
+      eleva.getState = () => {
+        return store.getState();
+      };
+      eleva.subscribe = callback => {
+        return store.subscribe(callback);
+      };
+
+      // Store original methods for cleanup
+      eleva._originalMount = originalMount;
+      eleva._originalMountComponents = originalMountComponents;
+    },
+    /**
+     * Uninstalls the plugin from the Eleva instance
+     *
+     * @param {Object} eleva - The Eleva instance
+     *
+     * @description
+     * Restores the original Eleva methods and removes all plugin-specific
+     * functionality. This method should be called when the plugin is no
+     * longer needed.
+     *
+     * @example
+     * // Uninstall the plugin
+     * StorePlugin.uninstall(app);
+     */
+    uninstall(eleva) {
+      // Restore original mount method
+      if (eleva._originalMount) {
+        eleva.mount = eleva._originalMount;
+        delete eleva._originalMount;
+      }
+
+      // Restore original _mountComponents method
+      if (eleva._originalMountComponents) {
+        eleva._mountComponents = eleva._originalMountComponents;
+        delete eleva._originalMountComponents;
+      }
+
+      // Remove store instance and utility methods
+      if (eleva.store) {
+        delete eleva.store;
+      }
+      if (eleva.createAction) {
+        delete eleva.createAction;
+      }
+      if (eleva.dispatch) {
+        delete eleva.dispatch;
+      }
+      if (eleva.getState) {
+        delete eleva.getState;
+      }
+      if (eleva.subscribe) {
+        delete eleva.subscribe;
+      }
+    }
+  };
+
+  exports.Attr = AttrPlugin;
+  exports.Props = PropsPlugin;
+  exports.Router = RouterPlugin;
+  exports.Store = StorePlugin;
+
+}));
+//# sourceMappingURL=eleva-plugins.umd.js.map