eleva 1.0.1 → 1.1.0

package/dist/eleva-plugins.umd.js

@@ -1,4 +1,4 @@
-/*! Eleva Plugins v1.0.1 | MIT License | https://elevajs.com */
+/*! Eleva Plugins v1.1.0 | MIT License | https://elevajs.com */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
   typeof define === 'function' && define.amd ? define(['exports'], factory) :
@@ -6,6 +6,37 @@
 })(this, (function (exports) { 'use strict';
 
   /**
+   * @module eleva/plugins/attr
+   * @fileoverview Attribute plugin providing ARIA, data, boolean, and dynamic attribute handling.
+   */ // ============================================================================
+  // TYPE DEFINITIONS
+  // ============================================================================
+  // -----------------------------------------------------------------------------
+  // External Type Imports
+  // -----------------------------------------------------------------------------
+  /**
+   * Type imports from the Eleva core library.
+   * @typedef {import('eleva').Eleva} Eleva
+   */ // -----------------------------------------------------------------------------
+  // Attr Type Definitions
+  // -----------------------------------------------------------------------------
+  /**
+   * Configuration options for the AttrPlugin.
+   * @typedef {Object} AttrPluginOptions
+   * @property {boolean} [enableAria=true]
+   *           Enable ARIA attribute handling.
+   * @property {boolean} [enableData=true]
+   *           Enable data attribute handling.
+   * @property {boolean} [enableBoolean=true]
+   *           Enable boolean attribute handling.
+   * @property {boolean} [enableDynamic=true]
+   *           Enable dynamic property detection.
+   * @description Configuration options passed to AttrPlugin.install().
+   */ /**
+   * Function signature for attribute update operations.
+   * @typedef {(oldEl: HTMLElement, newEl: HTMLElement) => void} AttributeUpdateFunction
+   * @description Updates attributes on oldEl to match newEl's attributes.
+   */ /**
    * A regular expression to match hyphenated lowercase letters.
    * @private
    * @type {RegExp}
@@ -46,33 +77,76 @@
       /**
      * Plugin version
      * @type {string}
-     */ version: "1.0.0",
+     */ version: "1.1.0",
       /**
      * Plugin description
      * @type {string}
      */ description: "Advanced attribute handling for Eleva components",
       /**
-     * Installs the plugin into the Eleva instance
+     * Installs the plugin into the Eleva instance.
+     *
+     * @public
+     * Method wrapping behavior:
+     * - Stores original `_patchNode` in `renderer._originalPatchNode`
+     * - Overrides `renderer._patchNode` to use enhanced attribute handling
+     * - Adds `renderer.updateAttributes` and `eleva.updateElementAttributes` helpers
+     * - Call `uninstall()` to restore original behavior
+     *
+     * @param {Eleva} eleva - The Eleva instance to enhance.
+     * @param {AttrPluginOptions} options - Plugin configuration options.
+     * @param {boolean} [options.enableAria=true] - Enable ARIA attribute handling.
+     *        Maps aria-* attributes to DOM properties (e.g., aria-expanded → ariaExpanded).
+     * @param {boolean} [options.enableData=true] - Enable data attribute handling.
+     *        Syncs data-* attributes with element.dataset for consistent access.
+     * @param {boolean} [options.enableBoolean=true] - Enable boolean attribute handling.
+     *        Treats empty strings and attribute names as true, "false" string as false.
+     * @param {boolean} [options.enableDynamic=true] - Enable dynamic property detection.
+     *        Searches element prototype chain for property matches (useful for custom elements).
+     * @returns {void}
+     * @example
+     * // Basic installation with defaults
+     * app.use(AttrPlugin);
      *
-     * @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
+     * @example
+     * // Custom configuration
+     * app.use(AttrPlugin, {
+     *   enableAria: true,
+     *   enableData: true,
+     *   enableBoolean: true,
+     *   enableDynamic: false  // Disable for performance
+     * });
+     *
+     * @example
+     * // Using ARIA attributes in templates
+     * template: (ctx) => `
+     *   <div role="dialog" aria-modal="true" aria-labelledby="title">
+     *     <h2 id="title">Modal Title</h2>
+     *     <button aria-expanded="${ctx.isOpen.value}">Toggle</button>
+     *   </div>
+     * `
+     * @see uninstall - Remove the plugin and restore original behavior.
      */ 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
+       * Processing order:
+       * 1. Skip event attributes (@click, @input) - handled by Eleva's event system
+       * 2. Skip unchanged attributes - optimization
+       * 3. ARIA attributes (aria-*): Map to DOM properties (aria-expanded → ariaExpanded)
+       * 4. Data attributes (data-*): Update both dataset and attribute
+       * 5. Boolean attributes: Handle empty string as true, "false" as false
+       * 6. Other attributes: Map to properties with dynamic detection for custom elements
+       * 7. Remove old attributes not present in new element
+       *
+       * Dynamic property detection (when enableDynamic=true):
+       * - Checks if property exists directly on element
+       * - Searches element's prototype chain for case-insensitive matches
+       * - Enables compatibility with custom elements and Web Components
+       *
+       * @inner
+       * @param {HTMLElement} oldEl - The original element to update (modified in-place).
+       * @param {HTMLElement} newEl - The reference element with desired attributes.
        * @returns {void}
        */ const updateAttributes = (oldEl, newEl)=>{
               const oldAttrs = oldEl.attributes;
@@ -143,8 +217,14 @@
               // 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) {
+              /**
+         * Overridden _patchNode method that uses enhanced attribute handling.
+         * Delegates to `updateAttributes` instead of the basic `_updateAttributes`.
+         *
+         * @param {Node} oldNode - The original DOM node to update.
+         * @param {Node} newNode - The new DOM node with desired state.
+         * @returns {void}
+         */ eleva.renderer._patchNode = function(oldNode, newNode) {
                   if (oldNode?._eleva_instance) return;
                   if (oldNode.nodeType === Node.TEXT_NODE) {
                       if (oldNode.nodeValue !== newNode.nodeValue) {
@@ -168,12 +248,21 @@
               options
           });
           // Add utility methods for manual attribute updates
-          eleva.updateElementAttributes = updateAttributes;
+          /** @type {AttributeUpdateFunction} */ eleva.updateElementAttributes = updateAttributes;
       },
       /**
-     * Uninstalls the plugin from the Eleva instance
+     * Uninstalls the plugin from the Eleva instance.
      *
-     * @param {Object} eleva - The Eleva instance
+     * @public
+     * @param {Eleva} eleva - The Eleva instance.
+     * @returns {void}
+     * @description
+     * Restores the original renderer patching behavior and removes
+     * `eleva.updateElementAttributes`.
+     * @example
+     * // Uninstall the plugin
+     * AttrPlugin.uninstall(app);
+     * @see install - Install the plugin.
      */ uninstall (eleva) {
           // Restore original _patchNode method if it exists
           if (eleva.renderer && eleva.renderer._originalPatchNode) {
@@ -190,60 +279,176 @@
   };
 
   /**
+   * @module eleva/plugins/router
+   * @fileoverview Client-side router plugin with hash, history, and query modes,
+   * navigation guards, and lifecycle hooks.
+   */ // ============================================================================
+  // TYPE DEFINITIONS
+  // ============================================================================
+  // -----------------------------------------------------------------------------
+  // External Type Imports
+  // -----------------------------------------------------------------------------
+  /**
+   * Type imports from the Eleva core library.
    * @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 {import('eleva').UnsubscribeFunction} UnsubscribeFunction
+   */ /**
+   * Generic type import.
+   * @template T
+   * @typedef {import('eleva').Signal<T>} Signal
+   */ // -----------------------------------------------------------------------------
+  // Router Events
+  // -----------------------------------------------------------------------------
+  /**
+   * Fired when the router initialization completes successfully.
+   * @event router:ready
+   * @type {Router}
+   */ /**
+   * Fired when an error occurs during navigation or route handling.
+   * @event router:error
+   * @type {Error}
+   */ /**
+   * Fired when no matching route is found for the requested path.
+   * @event router:notFound
+   * @type {{to: RouteLocation, from: RouteLocation | null, path: string}}
+   */ /**
+   * Fired before guards run, allowing plugins to block or redirect navigation.
+   * @event router:beforeEach
+   * @type {NavigationContext}
+   */ /**
+   * Fired before component resolution, allowing plugins to modify the resolve context.
+   * @event router:beforeResolve
+   * @type {ResolveContext}
+   */ /**
+   * Fired after components are resolved successfully.
+   * @event router:afterResolve
+   * @type {ResolveContext}
+   */ /**
+   * Fired after leaving the previous route.
+   * @event router:afterLeave
+   * @type {{to: RouteLocation, from: RouteLocation}}
+   */ /**
+   * Fired before DOM rendering begins.
+   * @event router:beforeRender
+   * @type {RenderContext}
+   */ /**
+   * Fired after DOM rendering completes.
+   * @event router:afterRender
+   * @type {RenderContext}
+   */ /**
+   * Fired after render for scroll behavior handling.
+   * @event router:scroll
+   * @type {ScrollContext}
+   */ /**
+   * Fired after entering the new route.
+   * @event router:afterEnter
+   * @type {{to: RouteLocation, from: RouteLocation | null}}
+   */ /**
+   * Fired after navigation completes successfully.
+   * @event router:afterEach
+   * @type {{to: RouteLocation, from: RouteLocation | null}}
+   */ /**
+   * Fired when a route is dynamically added.
+   * @event router:routeAdded
+   * @type {RouteDefinition}
+   */ /**
+   * Fired when a route is dynamically removed.
+   * @event router:routeRemoved
+   * @type {RouteDefinition}
+   */ // -----------------------------------------------------------------------------
+  // Router Data Types
+  // -----------------------------------------------------------------------------
   /**
-   * @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 {'hash' | 'history' | 'query'} RouterMode
+   */ /**
+   * Route parameters extracted from the URL path.
+   * @typedef {Record<string, string>} RouteParams
+   * @description Key-value pairs extracted from dynamic route segments (e.g., `/users/:id` → `{ id: '123' }`).
+   */ /**
+   * Query parameters from the URL query string.
+   * @typedef {Record<string, string>} QueryParams
+   * @description Key-value pairs from the URL query string (e.g., `?page=1&sort=name`).
    */ /**
+   * Navigation input parameters supporting multiple value types.
+   * @typedef {Record<string, string | number | boolean>} NavigationParams
+   * @description Parameters passed to navigation functions, automatically converted to strings in URLs.
+   */ /**
+   * Function signature for programmatic navigation.
+   * @typedef {(location: string | NavigationTarget, params?: NavigationParams) => Promise<boolean>} NavigateFunction
+   * @description Returns true if navigation succeeded, false if blocked by a guard.
+   */ /**
+   * Router configuration options.
    * @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.
+   * @property {RouterMode} [mode='hash']
+   *           The routing mode to use.
+   * @property {string} [queryParam='view']
+   *           Query parameter name for 'query' mode.
+   * @property {string} [viewSelector='view']
+   *           Base selector for the view element.
+   * @property {string} mount
+   *           CSS selector for the mount point element.
+   * @property {RouteDefinition[]} routes
+   *           Array of route definitions.
+   * @property {RouteComponent} [globalLayout]
+   *           Default layout for all routes.
+   * @property {NavigationGuard} [onBeforeEach]
+   *           Global navigation guard.
+   * @property {boolean} [autoStart=true]
+   *           Whether to start the router automatically.
    * @description Configuration options for the Router plugin.
    */ /**
+   * Object describing a navigation target for `router.navigate()`.
    * @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.
+   * @property {string} path
+   *           The target path (can include params like '/users/:id').
+   * @property {NavigationParams} [params]
+   *           Route parameters to inject.
+   * @property {NavigationParams} [query]
+   *           Query parameters to append.
+   * @property {boolean} [replace=false]
+   *           Whether to replace current history entry.
+   * @property {unknown} [state]
+   *           History state to pass.
    * @description Object describing a navigation target for `router.navigate()`.
    */ /**
+   * Saved scroll position.
    * @typedef {Object} ScrollPosition
-   * @property {number} x - Horizontal scroll position.
-   * @property {number} y - Vertical scroll position.
+   * @property {number} x
+   *           Horizontal scroll position.
+   * @property {number} y
+   *           Vertical scroll position.
    * @description Represents a saved scroll position.
    */ /**
+   * Internal representation of a parsed route path segment.
    * @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).
+   * @property {'static' | 'param'} type
+   *           The segment type.
+   * @property {string} [value]
+   *           The segment value (static segments).
+   * @property {string} [name]
+   *           The parameter name (param segments).
    * @description Internal representation of a parsed route path segment.
    * @private
    */ /**
+   * Result of matching a path against route definitions.
    * @typedef {Object} RouteMatch
-   * @property {RouteDefinition} route - The matched route definition.
-   * @property {Record<string, string>} params - The extracted route parameters.
+   * @property {RouteDefinition} route
+   *           The matched route definition.
+   * @property {RouteParams} 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:
+   * Arbitrary metadata attached to routes for use in guards and components.
+   * @typedef {Record<string, unknown>} RouteMeta
+   * @description Common properties include:
    * - `requiresAuth: boolean` - Whether the route requires authentication
    * - `title: string` - Page title for the route
    * - `roles: string[]` - Required user roles
@@ -254,76 +459,119 @@
    *   meta: { requiresAuth: true, roles: ['admin'], title: 'Admin Dashboard' }
    * }
    */ /**
+   * Interface for the router's error handling system.
    * @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.
+   * @property {(error: Error, context: string, details?: Record<string, unknown>) => void} handle
+   *           Throws a formatted error.
+   * @property {(message: string, details?: Record<string, unknown>) => void} warn
+   *           Logs a warning.
+   * @property {(message: string, error: Error, details?: Record<string, unknown>) => void} log
+   *           Logs an error without throwing.
    * @description Interface for the router's error handling system.
-   */ // ============================================
-  // Event Callback Type Definitions
-  // ============================================
+   */ // -----------------------------------------------------------------------------
+  // Event Callback Types
+  // -----------------------------------------------------------------------------
   /**
+   * Callback for `router:beforeEach` event.
    * @callback NavigationContextCallback
-   * @param {NavigationContext} context - The navigation context (can be modified to block/redirect).
+   * @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.
+   * @description Modify context to control navigation flow.
    */ /**
+   * Callback for `router:beforeResolve` and `router:afterResolve` events.
    * @callback ResolveContextCallback
-   * @param {ResolveContext} context - The resolve context (can be modified to block/redirect).
+   * @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 for `router:beforeRender` and `router:afterRender` events.
    * @callback RenderContextCallback
-   * @param {RenderContext} context - The render context.
+   * @param {RenderContext} context
+   *        The render context.
    * @returns {void | Promise<void>}
    * @description Callback for `router:beforeRender` and `router:afterRender` events.
    */ /**
+   * Callback for `router:scroll` event.
    * @callback ScrollContextCallback
-   * @param {ScrollContext} context - The scroll context with saved position info.
+   * @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.
+   * @description Use to implement custom scroll behavior.
    */ /**
+   * Callback for `router:afterEnter`, `router:afterLeave`, `router:afterEach` events.
    * @callback RouteChangeCallback
-   * @param {RouteLocation} to - The target route location.
-   * @param {RouteLocation | null} from - The source route location.
+   * @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.
    */ /**
+   * Router context injected into component setup as `ctx.router`.
+   * @typedef {Object} RouterContext
+   * @property {NavigateFunction} navigate
+   *           Programmatic navigation function.
+   * @property {Signal<RouteLocation | null>} current
+   *           Reactive signal for current route.
+   * @property {Signal<RouteLocation | null>} previous
+   *           Reactive signal for previous route.
+   * @property {RouteParams} params
+   *           Current route params (getter).
+   * @property {QueryParams} query
+   *           Current route query (getter).
+   * @property {string} path
+   *           Current route path (getter).
+   * @property {string} fullUrl
+   *           Current routed URL string (getter).
+   * @property {RouteMeta} meta
+   *           Current route meta (getter).
+   * @description Injected into component setup as `ctx.router`.
+   */ /**
+   * Callback for `router:error` event.
    * @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).
+   * @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.
+   * @description Callback for `router:error` event.
    */ /**
+   * Callback for `router:ready` event.
    * @callback RouterReadyCallback
-   * @param {Router} router - The router instance.
+   * @param {Router} router
+   *        The router instance.
    * @returns {void | Promise<void>}
    * @description Callback for `router:ready` event.
    */ /**
+   * Callback for `router:routeAdded` event.
    * @callback RouteAddedCallback
-   * @param {RouteDefinition} route - The added route definition.
+   * @param {RouteDefinition} route
+   *        The added route definition.
    * @returns {void | Promise<void>}
    * @description Callback for `router:routeAdded` event.
    */ /**
+   * Callback for `router:routeRemoved` event.
    * @callback RouteRemovedCallback
-   * @param {RouteDefinition} route - The removed route definition.
+   * @param {RouteDefinition} route
+   *        The removed route definition.
    * @returns {void | Promise<void>}
    * @description Callback for `router:routeRemoved` event.
-   */ // ============================================
-  // Core Type Definitions (continued)
-  // ============================================
+   */ // ============================================================================
+  // CORE IMPLEMENTATION
+  // ============================================================================
   /**
    * 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.
+     * @param {Record<string, unknown>} details - Additional error details.
      * @throws {Error} The formatted error.
      */ handle (error, context, details = {}) {
           const message = `[ElevaRouter] ${context}: ${error.message}`;
@@ -342,7 +590,7 @@
       /**
      * Logs a warning without throwing an error.
      * @param {string} message - The warning message.
-     * @param {Object} details - Additional warning details.
+     * @param {Record<string, unknown>} details - Additional warning details.
      */ warn (message, details = {}) {
           console.warn(`[ElevaRouter] ${message}`, details);
       },
@@ -350,7 +598,7 @@
      * Logs an error without throwing.
      * @param {string} message - The error message.
      * @param {Error} error - The original error.
-     * @param {Object} details - Additional error details.
+     * @param {Record<string, unknown>} details - Additional error details.
      */ log (message, error, details = {}) {
           console.error(`[ElevaRouter] ${message}`, {
               error,
@@ -359,26 +607,37 @@
       }
   };
   /**
+   * Represents the current or target location in the router.
    * @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.
+   * @property {string} path
+   *           The path of the route (e.g., '/users/123').
+   * @property {QueryParams} query
+   *           Query parameters as key-value pairs.
+   * @property {string} fullUrl
+   *           The routed URL string (path plus query).
+   * @property {RouteParams} params
+   *           Dynamic route parameters.
+   * @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 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.
+   * Return value of a navigation guard.
    * - `true` or `undefined/void`: Allow navigation
    * - `false`: Abort navigation
    * - `string`: Redirect to path
    * - `NavigationTarget`: Redirect with options
+   * @typedef {boolean | string | NavigationTarget | void} NavigationGuardResult
    */ /**
+   * Navigation guard function that controls navigation flow.
    * @callback NavigationGuard
-   * @param {RouteLocation} to - The target route location.
-   * @param {RouteLocation | null} from - The source route location (null on initial navigation).
+   * @param {RouteLocation} to
+   *        The target route location.
+   * @param {RouteLocation | null} from
+   *        The source route location (null on initial).
    * @returns {NavigationGuardResult | Promise<NavigationGuardResult>}
    * @description A function that controls navigation flow. Runs before navigation is confirmed.
    * @example
@@ -390,9 +649,12 @@
    *   // Allow navigation (implicit return undefined)
    * };
    */ /**
+   * Navigation hook for side effects. Does not affect navigation flow.
    * @callback NavigationHook
-   * @param {RouteLocation} to - The target route location.
-   * @param {RouteLocation | null} from - The source route location.
+   * @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
@@ -401,11 +663,16 @@
    *   analytics.trackPageView(to.path);
    * };
    */ /**
+   * Interface for router plugins.
    * @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().
+   * @property {string} name
+   *           Unique plugin identifier.
+   * @property {string} [version]
+   *           Plugin version (recommended to match router version).
+   * @property {(router: Router, options?: Record<string, unknown>) => 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 = {
@@ -418,57 +685,93 @@
    *   }
    * };
    */ /**
+   * Context object for navigation events that plugins can modify.
    * @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.
+   * @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 | NavigationTarget | null} redirectTo
+   *           Redirect target if set.
+   * @description Passed to navigation events. Plugins can modify to control navigation flow.
    */ /**
+   * Context object for component resolution events.
    * @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.
+   * @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 | NavigationTarget | null} redirectTo
+   *           Redirect target if set.
+   * @description Passed to component resolution events.
    */ /**
+   * Context object for render 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.
+   * @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 Passed to render events.
    */ /**
+   * Context object for scroll 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.
+   * @property {RouteLocation} to
+   *           The target route location.
+   * @property {RouteLocation | null} from
+   *           The source route location.
+   * @property {{x: number, y: number} | null} savedPosition
+   *           Saved position (back/forward nav).
+   * @description 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')`)
+   * - `() => ComponentDefinition`: Factory function returning a component
+   * - `() => Promise<ComponentDefinition>`: Async factory function
+   * - `() => Promise<{default: ComponentDefinition}>`: Lazy-loaded module (e.g., `() => import('./Page.js')`)
+   * @typedef {string | ComponentDefinition | (() => ComponentDefinition | Promise<ComponentDefinition | {default: ComponentDefinition}>)} RouteComponent
    */ /**
+   * Defines a route in the application.
    * @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).
+   * @property {string} path
+   *           URL path pattern. Supports:
+   *           - Static: '/about'
+   *           - Dynamic params: '/users/:id'
+   *           - Wildcard: '*' (catch-all, conventionally 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.
+   * @note Nested routes are not supported. Use shared layouts with flat routes instead.
    * @example
    * // Static route
    * { path: '/about', component: AboutPage }
@@ -484,10 +787,10 @@
    *   beforeEnter: (to, from) => isLoggedIn() || '/login'
    * }
    *
-   * // Catch-all 404 route (must be last)
+   * // Catch-all 404 route (conventionally last)
    * { path: '*', component: NotFoundPage }
    */ /**
-   * @class Router
+   * @class 🛤️ Router
    * @classdesc A powerful, reactive, and flexible Router Plugin for Eleva.
    * This class manages all routing logic, including state, navigation, and rendering.
    *
@@ -513,15 +816,15 @@
    * | `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:error` | {@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
+   * - `currentParams: Signal<RouteParams>` - Current route params
+   * - `currentQuery: Signal<QueryParams>` - Current query params
    * - `currentLayout: Signal<MountResult | null>` - Mounted layout instance
    * - `currentView: Signal<MountResult | null>` - Mounted view instance
    * - `isReady: Signal<boolean>` - Router readiness state
@@ -596,7 +899,7 @@
      * 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.
+     * @returns {{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") {
@@ -640,6 +943,11 @@
       /**
      * Starts the router, initializes event listeners, and performs the initial navigation.
      * @returns {Promise<Router>} The router instance for method chaining.
+     * @listens window:hashchange In hash mode, triggers route changes.
+     * @listens window:popstate In history/query mode, triggers route changes.
+     * @emits router:ready When initialization completes successfully.
+     * @see destroy - Stop the router and clean up listeners.
+     * @see navigate - Programmatically navigate to a route.
      *
      * @example
      * // Basic usage
@@ -684,8 +992,11 @@
           return this;
       }
       /**
-     * Stops the router and cleans up all event listeners and mounted components.
+     * Stops the router and cleans up event listeners.
+     * Unmounts the current layout instance if present.
+     * @async
      * @returns {Promise<void>}
+     * @see start - Restart the router after destroying.
      */ async destroy() {
           if (!this.isStarted) return;
           // Clean up plugins
@@ -709,6 +1020,7 @@
       /**
      * Alias for destroy(). Stops the router and cleans up all resources.
      * Provided for semantic consistency (start/stop pattern).
+     * @async
      * @returns {Promise<void>}
      *
      * @example
@@ -720,9 +1032,13 @@
       }
       /**
      * Programmatically navigates to a new route.
+     * @async
      * @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).
+     * @param {NavigationParams} [params] - Route parameters (only used when location is a string).
      * @returns {Promise<boolean>} True if navigation succeeded, false if blocked by guards or failed.
+     * @emits router:error When navigation fails due to an exception.
+     * @see start - Initialize the router before navigating.
+     * @see currentRoute - Access the current route after navigation.
      *
      * @example
      * // Basic navigation
@@ -785,7 +1101,7 @@
               return navigationSuccessful;
           } catch (error) {
               this.errorHandler.log("Navigation failed", error);
-              await this.emitter.emit("router:onError", error);
+              await this.emitter.emit("router:error", error);
               return false;
           }
       }
@@ -805,7 +1121,7 @@
      * @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.
+     * @returns {boolean} True if the routes are the same.
      */ _isSameRoute(path, params, query) {
           const current = this.currentRoute.value;
           if (!current) return false;
@@ -815,7 +1131,16 @@
       }
       /**
      * Injects dynamic parameters into a path string.
+     * Replaces `:param` placeholders with URL-encoded values from the params object.
+     *
      * @private
+     * @param {string} path - The path pattern containing `:param` placeholders.
+     * @param {RouteParams} params - Key-value pairs to inject into the path.
+     * @returns {string} The path with all parameters replaced.
+     *
+     * @example
+     * this._buildPath('/users/:id/posts/:postId', { id: '123', postId: '456' });
+     * // Returns: '/users/123/posts/456'
      */ _buildPath(path, params) {
           let result = path;
           for (const [key, value] of Object.entries(params)){
@@ -827,8 +1152,12 @@
       }
       /**
      * The handler for browser-initiated route changes (e.g., back/forward buttons).
+     *
      * @private
+     * @async
      * @param {boolean} [isPopState=true] - Whether this is a popstate event (back/forward navigation).
+     * @returns {Promise<void>}
+     * @emits router:error When route change handling fails.
      */ async _handleRouteChange(isPopState = true) {
           if (this._isNavigating) return;
           try {
@@ -847,26 +1176,30 @@
               this.errorHandler.log("Route change handling failed", error, {
                   currentUrl: typeof window !== "undefined" ? window.location.href : ""
               });
-              await this.emitter.emit("router:onError", error);
+              await this.emitter.emit("router:error", 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
+     * @async
      * @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.
+     * @returns {Promise<boolean>} `true` if navigation succeeded, `false` if aborted.
+     * @emits router:notFound When no matching route is found.
+     * @emits router:beforeResolve Before component resolution (can block/redirect).
+     * @emits router:afterResolve After components are resolved.
+     * @emits router:afterLeave After leaving the previous route.
+     * @emits router:beforeRender Before DOM rendering.
+     * @emits router:afterRender After DOM rendering completes.
+     * @emits router:scroll After render, for scroll behavior handling.
+     * @emits router:afterEnter After entering the new route.
+     * @emits router:afterEach After navigation completes successfully.
+     * @emits router:error When an error occurs during navigation.
+     * @see _runGuards - Guard execution.
+     * @see _resolveComponents - Component resolution.
+     * @see _render - DOM rendering.
      */ async _proceedWithNavigation(fullPath, isPopState = false) {
           const from = this.currentRoute.value;
           const [path, queryString] = (fullPath || "/").split("?");
@@ -886,7 +1219,7 @@
                       }
                   };
               } else {
-                  await this.emitter.emit("router:onError", new Error(`Route not found: ${toLocation.path}`), toLocation, from);
+                  await this.emitter.emit("router:error", new Error(`Route not found: ${toLocation.path}`), toLocation, from);
                   return false;
               }
           }
@@ -973,7 +1306,7 @@
               };
               await this.emitter.emit("router:beforeRender", renderContext);
               // 9. Render the new components.
-              await this._render(layoutComponent, pageComponent, to);
+              await this._render(layoutComponent, pageComponent);
               // 10. Emit afterRender event - plugins can trigger animations
               await this.emitter.emit("router:afterRender", renderContext);
               // 11. Emit scroll event - plugins can handle scroll restoration
@@ -995,7 +1328,7 @@
                   to,
                   from
               });
-              await this.emitter.emit("router:onError", error, to, from);
+              await this.emitter.emit("router:error", error, to, from);
               return false;
           }
       }
@@ -1011,7 +1344,8 @@
      * @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.
+     * @returns {Promise<boolean>} `false` if navigation should be aborted.
+     * @emits router:beforeEach Before guards run (can block/redirect via context).
      */ async _runGuards(to, from, route) {
           // Create navigation context that plugins can modify to block navigation
           /** @type {NavigationContext} */ const navContext = {
@@ -1072,7 +1406,8 @@
       /**
      * Resolves a function component definition to a component object.
      * @private
-     * @param {Function} def - The function to resolve.
+     * @async
+     * @param {() => ComponentDefinition | Promise<ComponentDefinition | { default: ComponentDefinition }>} def - The function to resolve.
      * @returns {Promise<ComponentDefinition>} The resolved component.
      * @throws {Error} If the function fails to load the component.
      */ async _resolveFunctionComponent(def) {
@@ -1091,7 +1426,7 @@
       /**
      * Validates a component definition object.
      * @private
-     * @param {any} def - The component definition to validate.
+     * @param {unknown} def - The component definition to validate.
      * @returns {ComponentDefinition} The validated component.
      * @throws {Error} If the component definition is invalid.
      */ _validateComponentDefinition(def) {
@@ -1110,7 +1445,7 @@
       /**
      * Resolves a component definition to a component object.
      * @private
-     * @param {any} def - The component definition to resolve.
+     * @param {unknown} def - The component definition to resolve.
      * @returns {Promise<ComponentDefinition | null>} The resolved component or null.
      */ async _resolveComponent(def) {
           if (def === null || def === undefined) {
@@ -1132,8 +1467,10 @@
       /**
      * Asynchronously resolves the layout and page components for a route.
      * @private
+     * @async
      * @param {RouteDefinition} route - The route to resolve components for.
      * @returns {Promise<{layoutComponent: ComponentDefinition | null, pageComponent: ComponentDefinition}>}
+     * @throws {Error} If page component cannot be resolved.
      */ async _resolveComponents(route) {
           const effectiveLayout = route.layout || this.options.globalLayout;
           try {
@@ -1159,9 +1496,24 @@
       }
       /**
      * Renders the components for the current route into the DOM.
+     *
+     * Rendering algorithm:
+     * 1. Find the mount element using options.mount selector
+     * 2. If layoutComponent exists:
+     *    a. Mount layout to mount element
+     *    b. Find view element within layout (using viewSelector)
+     *    c. Mount page component to view element
+     * 3. If no layoutComponent:
+     *    a. Mount page component directly to mount element
+     *    b. Set currentLayout to null
+     *
      * @private
+     * @async
      * @param {ComponentDefinition | null} layoutComponent - The pre-loaded layout component.
      * @param {ComponentDefinition} pageComponent - The pre-loaded page component.
+     * @returns {Promise<void>}
+     * @throws {Error} If mount element is not found in the DOM.
+     * @throws {Error} If component mounting fails (propagated from eleva.mount).
      */ async _render(layoutComponent, pageComponent) {
           const mountEl = document.querySelector(this.options.mount);
           if (!mountEl) {
@@ -1185,8 +1537,8 @@
      * 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.
+     * @param {unknown} defaultValue - The default value if property is undefined.
+     * @returns {() => unknown} A getter function.
      */ _createRouteGetter(property, defaultValue) {
           return ()=>this.currentRoute.value?.[property] ?? defaultValue;
       }
@@ -1201,7 +1553,7 @@
           return {
               ...component,
               async setup (ctx) {
-                  ctx.router = {
+                  /** @type {RouterContext} */ ctx.router = {
                       navigate: self.navigate.bind(self),
                       current: self.currentRoute,
                       previous: self.previousRoute,
@@ -1228,9 +1580,13 @@
       }
       /**
      * Recursively wraps all child components to ensure they have access to router context.
+     * String component references are returned as-is (context injected during mount).
+     * Objects are wrapped with router context and their children are recursively wrapped.
+     *
      * @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.
+     * @see _wrapComponent - Single component wrapping.
      */ _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
@@ -1287,7 +1643,15 @@
       }
       /**
      * Parses a query string into a key-value object.
+     * Uses URLSearchParams for robust parsing of encoded values.
+     *
      * @private
+     * @param {string} queryString - The query string to parse (without leading '?').
+     * @returns {QueryParams} Key-value pairs from the query string.
+     *
+     * @example
+     * this._parseQuery('foo=bar&baz=qux');
+     * // Returns: { foo: 'bar', baz: 'qux' }
      */ _parseQuery(queryString) {
           const query = {};
           if (queryString) {
@@ -1339,10 +1703,12 @@
       /**
      * Adds a new route dynamically at runtime.
      * The route will be processed and available for navigation immediately.
+     * Routes are inserted before the wildcard (*) route if one exists.
      *
      * @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.
+     * @returns {() => void} A function to remove the added route (returns no-op if route was invalid).
+     * @emits router:routeAdded When a route is successfully added.
      *
      * @example
      * // Add a route dynamically
@@ -1390,6 +1756,7 @@
      *
      * @param {string} path - The path of the route to remove.
      * @returns {boolean} True if the route was removed, false if not found.
+     * @emits router:routeRemoved When a route is successfully removed.
      *
      * @example
      * router.removeRoute('/dynamic');
@@ -1477,6 +1844,7 @@
      * 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.
+     * @listens router:afterEnter
      */ onAfterEnter(hook) {
           return this.emitter.on("router:afterEnter", hook);
       }
@@ -1484,6 +1852,7 @@
      * 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.
+     * @listens router:afterLeave
      */ onAfterLeave(hook) {
           return this.emitter.on("router:afterLeave", hook);
       }
@@ -1491,6 +1860,7 @@
      * 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.
+     * @listens router:afterEach
      */ onAfterEach(hook) {
           return this.emitter.on("router:afterEach", hook);
       }
@@ -1498,12 +1868,18 @@
      * 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.
+     * @listens router:error
      */ onError(handler) {
-          return this.emitter.on("router:onError", handler);
+          return this.emitter.on("router:error", handler);
       }
       /**
      * Registers a plugin with the router.
-     * @param {RouterPlugin} plugin - The plugin to register.
+     * Logs a warning if the plugin is already registered.
+     *
+     * @param {RouterPlugin} plugin - The plugin to register (must have install method).
+     * @param {Record<string, unknown>} [options={}] - Options to pass to plugin.install().
+     * @returns {void}
+     * @throws {Error} If plugin does not have an install method.
      */ use(plugin, options = {}) {
           if (typeof plugin.install !== "function") {
               this.errorHandler.handle(new Error("Plugin must have an install method"), "Plugin registration failed", {
@@ -1552,7 +1928,9 @@
       }
       /**
      * Sets a custom error handler. Used by error handling plugins.
-     * @param {Object} errorHandler - The error handler object with handle, warn, and log methods.
+     * Logs a warning if the provided handler is invalid (missing required methods).
+     * @param {RouterErrorHandler} errorHandler - The error handler object with handle, warn, and log methods.
+     * @returns {void}
      */ setErrorHandler(errorHandler) {
           if (errorHandler && typeof errorHandler.handle === "function" && typeof errorHandler.warn === "function" && typeof errorHandler.log === "function") {
               this.errorHandler = errorHandler;
@@ -1564,6 +1942,7 @@
      * Creates an instance of the Router.
      * @param {Eleva} eleva - The Eleva framework instance.
      * @param {RouterOptions} options - The configuration options for the router.
+     * @throws {Error} If the routing mode is invalid.
      */ constructor(eleva, options = {}){
           /** @type {Eleva} The Eleva framework instance. */ this.eleva = eleva;
           /** @type {RouterOptions} The merged router options. */ this.options = {
@@ -1573,40 +1952,30 @@
               ...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 {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 = [];
+          /** @private @type {UnsubscribeFunction[]} 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<RouteParams>} A reactive signal holding the current route's parameters. */ this.currentParams = new this.eleva.signal({});
+          /** @type {Signal<QueryParams>} A reactive signal holding the current route's query parameters. */ this.currentQuery = new this.eleva.signal({});
+          /** @type {Signal<MountResult | null>} A reactive signal for the currently mounted layout instance. */ this.currentLayout = new this.eleva.signal(null);
+          /** @type {Signal<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 = [];
+          /** @private @type {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;
+          /** @type {RouterErrorHandler} 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();
       }
   }
   /**
-   * @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 applications.
    * This plugin provides comprehensive client-side routing functionality including:
@@ -1645,7 +2014,7 @@
       /**
      * Plugin version
      * @type {string}
-     */ version: "1.0.1",
+     */ version: "1.1.0",
       /**
      * Plugin description
      * @type {string}
@@ -1653,16 +2022,25 @@
       /**
      * 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
+     * @public
+     * @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='view'] - The query parameter to use in 'query' mode.
+     * @param {string} [options.viewSelector='view'] - Base selector for the view element (matched as #id, .class, [data-*], or raw selector).
+     * @param {boolean} [options.autoStart=true] - Whether to start the router automatically.
+     * @param {NavigationGuard} [options.onBeforeEach] - A global guard executed before every navigation.
+     * @param {RouteComponent} [options.globalLayout] - A global layout for all routes.
+     * @returns {Router} The created router instance.
+     * @throws {Error} If 'mount' option is not provided.
+     * @throws {Error} If 'routes' option is not an array.
+     * @throws {Error} If component registration fails during route processing.
+     * @description
+     * Registers route/layout components, sets `eleva.router`, and adds helpers
+     * (`eleva.navigate`, `eleva.getCurrentRoute`, `eleva.getRouteParams`, `eleva.getRouteQuery`).
+     * When `autoStart` is enabled, startup is scheduled via microtask.
      *
      * @example
      * // main.js
@@ -1692,9 +2070,10 @@
        * 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
+       * @inner
+       * @param {unknown} 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) {
@@ -1718,7 +2097,7 @@
               }
           });
           const router = new Router(eleva, options);
-          eleva.router = router;
+          /** @type {Router} */ eleva.router = router;
           if (options.autoStart !== false) {
               queueMicrotask(()=>router.start());
           }
@@ -1733,16 +2112,22 @@
               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;
+          /** @type {NavigateFunction} */ eleva.navigate = router.navigate.bind(router);
+          /** @type {() => RouteLocation | null} */ eleva.getCurrentRoute = ()=>router.currentRoute.value;
+          /** @type {() => RouteParams} */ eleva.getRouteParams = ()=>router.currentParams.value;
+          /** @type {() => QueryParams} */ eleva.getRouteQuery = ()=>router.currentQuery.value;
           return router;
       },
       /**
-     * Uninstalls the plugin from the Eleva instance
+     * Uninstalls the plugin from the Eleva instance.
      *
-     * @param {Eleva} eleva - The Eleva instance
+     * @public
+     * @async
+     * @param {Eleva} eleva - The Eleva instance.
+     * @returns {Promise<void>}
+     * @description
+     * Destroys the router instance, removes `eleva.router`, and deletes helper methods
+     * (`eleva.navigate`, `eleva.getCurrentRoute`, `eleva.getRouteParams`, `eleva.getRouteQuery`).
      */ async uninstall (eleva) {
           if (eleva.router) {
               await eleva.router.destroy();
@@ -1761,6 +2146,194 @@
   };
 
   /**
+   * @module eleva/plugins/store
+   * @fileoverview Reactive state management plugin with namespaced modules,
+   * persistence, and subscription system.
+   */ // ============================================================================
+  // TYPE DEFINITIONS
+  // ============================================================================
+  // -----------------------------------------------------------------------------
+  // External Type Imports
+  // -----------------------------------------------------------------------------
+  /**
+   * Type imports from the Eleva core library.
+   * @typedef {import('eleva').Eleva} Eleva
+   * @typedef {import('eleva').ComponentDefinition} ComponentDefinition
+   * @typedef {import('eleva').ComponentContext} ComponentContext
+   * @typedef {import('eleva').SetupResult} SetupResult
+   * @typedef {import('eleva').ComponentProps} ComponentProps
+   * @typedef {import('eleva').ChildrenMap} ChildrenMap
+   * @typedef {import('eleva').MountResult} MountResult
+   */ /**
+   * Generic type import.
+   * @template T
+   * @typedef {import('eleva').Signal<T>} Signal
+   */ // -----------------------------------------------------------------------------
+  // Store Type Definitions
+  // -----------------------------------------------------------------------------
+  /**
+   * Mutation record emitted to subscribers.
+   * @typedef {Object} StoreMutation
+   * @property {string} type
+   *           The action name that was dispatched.
+   * @property {unknown} payload
+   *           The payload passed to the action.
+   * @property {number} timestamp
+   *           Unix timestamp of when the mutation occurred.
+   * @description Record passed to subscribers when state changes via dispatch.
+   * @example
+   * store.subscribe((mutation, state) => {
+   *   console.log(`Action: ${mutation.type}`);
+   *   console.log(`Payload: ${mutation.payload}`);
+   *   console.log(`Time: ${new Date(mutation.timestamp)}`);
+   * });
+   */ /**
+   * Store configuration options.
+   * @typedef {Object} StoreOptions
+   * @property {Record<string, unknown>} [state]
+   *           Initial state object.
+   * @property {Record<string, ActionFunction>} [actions]
+   *           Action functions for state mutations.
+   * @property {Record<string, StoreModule>} [namespaces]
+   *           Namespaced modules for organizing store.
+   * @property {StorePersistenceOptions} [persistence]
+   *           Persistence configuration.
+   * @property {boolean} [devTools]
+   *           Enable development tools integration.
+   * @property {StoreErrorHandler} [onError]
+   *           Error handler function.
+   * @description Configuration options passed to StorePlugin.install().
+   * @example
+   * app.use(StorePlugin, {
+   *   state: { count: 0, user: null },
+   *   actions: {
+   *     increment: (state) => state.count.value++,
+   *     setUser: (state, user) => state.user.value = user
+   *   },
+   *   persistence: { enabled: true, key: 'my-app' }
+   * });
+   */ /**
+   * Namespaced store module definition.
+   * @typedef {Object} StoreModule
+   * @property {Record<string, unknown>} state
+   *           Module state.
+   * @property {Record<string, ActionFunction>} [actions]
+   *           Module actions.
+   * @description Defines a namespaced module for organizing related state and actions.
+   * @example
+   * // Define a module
+   * const authModule = {
+   *   state: { user: null, token: null },
+   *   actions: {
+   *     login: (state, { user, token }) => {
+   *       state.auth.user.value = user;
+   *       state.auth.token.value = token;
+   *     }
+   *   }
+   * };
+   *
+   * // Register dynamically
+   * store.registerModule('auth', authModule);
+   */ /**
+   * Store persistence configuration.
+   * @typedef {Object} StorePersistenceOptions
+   * @property {boolean} [enabled]
+   *           Enable state persistence.
+   * @property {string} [key]
+   *           Storage key (default: "eleva-store").
+   * @property {'localStorage' | 'sessionStorage'} [storage]
+   *           Storage type.
+   * @property {string[]} [include]
+   *           Dot-path prefixes to persist (e.g., "auth.user").
+   * @property {string[]} [exclude]
+   *           Dot-path prefixes to exclude.
+   * @description Configuration for persisting store state to localStorage or sessionStorage.
+   * @example
+   * // Persist only specific state paths
+   * persistence: {
+   *   enabled: true,
+   *   key: 'my-app-store',
+   *   storage: 'localStorage',
+   *   include: ['user', 'settings.theme']
+   * }
+   *
+   * @example
+   * // Exclude sensitive data
+   * persistence: {
+   *   enabled: true,
+   *   exclude: ['auth.token', 'temp']
+   * }
+   */ /**
+   * Store error handler callback.
+   * @typedef {(error: Error, context: string) => void} StoreErrorHandler
+   * @description Custom error handler for store operations.
+   * @example
+   * app.use(StorePlugin, {
+   *   onError: (error, context) => {
+   *     console.error(`Store error in ${context}:`, error);
+   *     // Send to error tracking service
+   *     errorTracker.capture(error, { context });
+   *   }
+   * });
+   */ /**
+   * Reactive state tree containing signals and nested namespaces.
+   * @typedef {Record<string, Signal<unknown> | Record<string, unknown>>} StoreState
+   * @description Represents the store's reactive state structure with support for nested modules.
+   */ /**
+   * Action function signature for store actions.
+   * @typedef {(state: StoreState, payload?: unknown) => unknown} ActionFunction
+   * @description Function that receives state and optional payload, returns action result.
+   */ /**
+   * Dispatch function signature for triggering actions.
+   * @typedef {(actionName: string, payload?: unknown) => Promise<unknown>} DispatchFunction
+   * @description Dispatches an action by name with optional payload, returns action result.
+   */ /**
+   * Subscribe callback signature for mutation listeners.
+   * @typedef {(mutation: StoreMutation, state: StoreState) => void} SubscribeCallback
+   * @description Called after each successful action dispatch with mutation details and current state.
+   */ /**
+   * Store API exposed to components via ctx.store.
+   * @typedef {Object} StoreApi
+   * @property {StoreState} state
+   *           Reactive state signals (supports nested modules).
+   * @property {DispatchFunction} dispatch
+   *           Dispatch an action by name with optional payload.
+   * @property {(callback: SubscribeCallback) => () => void} subscribe
+   *           Subscribe to state mutations. Returns unsubscribe function.
+   * @property {() => Record<string, unknown>} getState
+   *           Get a snapshot of current state values.
+   * @property {(namespace: string, module: StoreModule) => void} registerModule
+   *           Register a namespaced module dynamically.
+   * @property {(namespace: string) => void} unregisterModule
+   *           Unregister a namespaced module.
+   * @property {(key: string, initialValue: unknown) => Signal<unknown>} createState
+   *           Create a new state signal dynamically.
+   * @property {(name: string, actionFn: ActionFunction) => void} createAction
+   *           Register a new action dynamically.
+   * @property {new <T>(value: T) => Signal<T>} signal
+   *           Signal class constructor for manual state creation.
+   * @description The store API injected into component setup as `ctx.store`.
+   * @example
+   * app.component('Counter', {
+   *   setup({ store }) {
+   *     // Access reactive state
+   *     const count = store.state.count;
+   *
+   *     // Dispatch actions
+   *     const increment = () => store.dispatch('increment');
+   *
+   *     // Subscribe to changes
+   *     const unsub = store.subscribe((mutation) => {
+   *       console.log('State changed:', mutation.type);
+   *     });
+   *
+   *     return { count, increment, onUnmount: () => unsub() };
+   *   },
+   *   template: (ctx) => `<button @click="increment">${ctx.count.value}</button>`
+   * });
+   * @see StoreMutation - Mutation record structure.
+   * @see StoreModule - Module definition for namespaces.
+   */ /**
    * @class 🏪 StorePlugin
    * @classdesc A powerful reactive state management plugin for Eleva that enables sharing
    * reactive data across the entire application. The Store plugin provides a centralized,
@@ -1787,7 +2360,7 @@
    *   },
    *   actions: {
    *     increment: (state) => state.counter.value++,
-   *     addTodo: (state, todo) => state.todos.value.push(todo),
+   *     addTodo: (state, todo) => state.todos.value = [...state.todos.value, todo],
    *     setUser: (state, user) => state.user.value = user
    *   },
    *   persistence: {
@@ -1810,7 +2383,7 @@
    *     <div>
    *       <p>Hello ${ctx.user.value.name}!</p>
    *       <p>Count: ${ctx.count.value}</p>
-   *       <button onclick="ctx.increment()">+</button>
+   *       <button @click="increment">+</button>
    *     </div>
    *   `
    * });
@@ -1822,27 +2395,34 @@
       /**
      * Plugin version
      * @type {string}
-     */ version: "1.0.0",
+     */ version: "1.1.0",
       /**
      * Plugin description
      * @type {string}
      */ description: "Reactive state management for sharing data across the entire Eleva application",
       /**
-     * Installs the plugin into the Eleva instance
+     * 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
+     * @public
+     * @param {Eleva} eleva - The Eleva instance.
+     * @param {StoreOptions} options - Plugin configuration options.
+     * @param {Record<string, unknown>} [options.state={}] - Initial state object.
+     * @param {Record<string, ActionFunction>} [options.actions={}] - Action functions for state mutations.
+     * @param {Record<string, StoreModule>} [options.namespaces={}] - Namespaced modules for organizing store.
+     * @param {StorePersistenceOptions} [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 {string[]} [options.persistence.include] - Dot-path prefixes to persist (e.g., "auth.user")
+     * @param {string[]} [options.persistence.exclude] - Dot-path prefixes to exclude (applies when include is empty).
+     * @param {boolean} [options.devTools=false] - Enable development tools integration.
+     * @param {(error: Error, context: string) => void} [options.onError=null] - Error handler function.
+     * @returns {void}
+     * @description
+     * Installs the store and injects `store` into component setup context by wrapping
+     * `eleva.mount` and `eleva._mountComponents`. Also exposes `eleva.store` and
+     * helper methods (`eleva.dispatch`, `eleva.getState`, `eleva.subscribe`, `eleva.createAction`).
+     * Uninstall restores the originals.
      *
      * @example
      * // Basic installation
@@ -1862,12 +2442,12 @@
      *       state: { user: null, token: null },
      *       actions: {
      *         login: (state, { user, token }) => {
-     *           state.user.value = user;
-     *           state.token.value = token;
+     *           state.auth.user.value = user;
+     *           state.auth.token.value = token;
      *         },
      *         logout: (state) => {
-     *           state.user.value = null;
-     *           state.token.value = null;
+     *           state.auth.user.value = null;
+     *           state.auth.token.value = null;
      *         }
      *       }
      *     }
@@ -1880,12 +2460,18 @@
      */ install (eleva, options = {}) {
           const { state = {}, actions = {}, namespaces = {}, persistence = {}, devTools = false, onError = null } = options;
           /**
-       * Store instance that manages all state and provides the API
+       * @class Store
+       * @classdesc Store instance that manages all state and provides the API.
        * @private
        */ class Store {
               /**
-         * Initializes the root state and actions
+         * Initializes the root state and actions.
+         * Creates reactive signals for each state property and copies actions.
+         *
          * @private
+         * @param {Record<string, unknown>} initialState - The initial state key-value pairs.
+         * @param {Record<string, ActionFunction>} initialActions - The action functions to register.
+         * @returns {void}
          */ _initializeState(initialState, initialActions) {
                   // Create reactive signals for each state property
                   Object.entries(initialState).forEach(([key, value])=>{
@@ -1897,8 +2483,12 @@
                   };
               }
               /**
-         * Initializes namespaced modules
+         * Initializes namespaced modules.
+         * Creates namespace objects and populates them with state signals and actions.
+         *
          * @private
+         * @param {Record<string, StoreModule>} namespaces - Map of namespace names to module definitions.
+         * @returns {void}
          */ _initializeNamespaces(namespaces) {
                   Object.entries(namespaces).forEach(([namespace, module])=>{
                       const { state: moduleState = {}, actions: moduleActions = {} } = module;
@@ -1920,8 +2510,12 @@
                   });
               }
               /**
-         * Loads persisted state from storage
+         * Loads persisted state from storage.
+         * Reads from localStorage/sessionStorage and applies values to state signals.
+         * Does nothing if persistence is disabled or running in SSR environment.
+         *
          * @private
+         * @returns {void}
          */ _loadPersistedState() {
                   if (!this.persistence.enabled || typeof window === "undefined") {
                       return;
@@ -1942,8 +2536,14 @@
                   }
               }
               /**
-         * Applies persisted data to the current state
+         * Applies persisted data to the current state.
+         * Recursively updates signal values for paths that should be persisted.
+         *
          * @private
+         * @param {Record<string, unknown>} data - The persisted data object to apply.
+         * @param {Record<string, unknown>} [currentState=this.state] - The current state object to update.
+         * @param {string} [path=""] - The current dot-notation path (for include/exclude filtering).
+         * @returns {void}
          */ _applyPersistedData(data, currentState = this.state, path = "") {
                   Object.entries(data).forEach(([key, value])=>{
                       const fullPath = path ? `${path}.${key}` : key;
@@ -1959,8 +2559,12 @@
                   });
               }
               /**
-         * Determines if a state path should be persisted
+         * Determines if a state path should be persisted.
+         * Checks against include/exclude filters configured in persistence options.
+         *
          * @private
+         * @param {string} path - The dot-notation path to check (e.g., "auth.user").
+         * @returns {boolean} True if the path should be persisted, false otherwise.
          */ _shouldPersist(path) {
                   const { include, exclude } = this.persistence;
                   if (include && include.length > 0) {
@@ -1972,8 +2576,12 @@
                   return true;
               }
               /**
-         * Saves current state to storage
+         * Saves current state to storage.
+         * Extracts persistable data and writes to localStorage/sessionStorage.
+         * Does nothing if persistence is disabled or running in SSR environment.
+         *
          * @private
+         * @returns {void}
          */ _saveState() {
                   if (!this.persistence.enabled || typeof window === "undefined") {
                       return;
@@ -1991,8 +2599,13 @@
                   }
               }
               /**
-         * Extracts data that should be persisted
+         * Extracts data that should be persisted.
+         * Recursively extracts signal values for paths that pass persistence filters.
+         *
          * @private
+         * @param {Record<string, unknown>} [currentState=this.state] - The state object to extract from.
+         * @param {string} [path=""] - The current dot-notation path (for include/exclude filtering).
+         * @returns {Record<string, unknown>} The extracted data object with raw values (not signals).
          */ _extractPersistedData(currentState = this.state, path = "") {
                   const result = {};
                   Object.entries(currentState).forEach(([key, value])=>{
@@ -2013,8 +2626,12 @@
                   return result;
               }
               /**
-         * Sets up development tools integration
+         * Sets up development tools integration.
+         * Registers the store with Eleva DevTools if available and enabled.
+         * Does nothing if devTools is disabled, running in SSR, or DevTools not installed.
+         *
          * @private
+         * @returns {void}
          */ _setupDevTools() {
                   if (!this.devTools || typeof window === "undefined" || !window.__ELEVA_DEVTOOLS__) {
                       return;
@@ -2022,10 +2639,26 @@
                   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
+         * Dispatches an action to mutate the state.
+         *
+         * Execution flow:
+         * 1. Retrieves the action function (supports namespaced actions like "auth.login")
+         * 2. Records mutation for devtools/history (keeps last 100 mutations)
+         * 3. Executes action with await (actions can be sync or async)
+         * 4. Saves state if persistence is enabled
+         * 5. Notifies all subscribers with (mutation, state)
+         * 6. Notifies devtools if enabled
+         *
+         * @note Always returns a Promise regardless of whether the action is sync or async.
+         * Subscriber callbacks that throw are caught and passed to onError handler.
+         *
+         * @async
+         * @param {string} actionName - The name of the action to dispatch (supports dot notation for namespaces).
+         * @param {unknown} payload - The payload to pass to the action.
+         * @returns {Promise<unknown>} The result of the action (undefined if action returns nothing).
+         * @throws {Error} If action is not found or action function throws.
+         * @see subscribe - Listen for mutations triggered by dispatch.
+         * @see getState - Get current state values.
          */ async dispatch(actionName, payload) {
                   try {
                       const action = this._getAction(actionName);
@@ -2073,8 +2706,12 @@
                   }
               }
               /**
-         * Gets an action by name (supports namespaced actions)
+         * Gets an action by name (supports namespaced actions).
+         * Traverses the actions object using dot-notation path segments.
+         *
          * @private
+         * @param {string} actionName - The action name, supports dot notation for namespaces (e.g., "auth.login").
+         * @returns {ActionFunction | null} The action function if found and is a function, null otherwise.
          */ _getAction(actionName) {
                   const parts = actionName.split(".");
                   let current = this.actions;
@@ -2087,9 +2724,18 @@
                   return typeof current === "function" ? current : null;
               }
               /**
-         * Subscribes to store mutations
-         * @param {Function} callback - Callback function to call on mutations
-         * @returns {Function} Unsubscribe function
+         * Subscribes to store mutations.
+         * Callback is invoked after every successful action dispatch.
+         *
+         * @param {SubscribeCallback} callback
+         *        Called after each mutation with:
+         *        - mutation.type: The action name that was dispatched
+         *        - mutation.payload: The payload passed to the action
+         *        - mutation.timestamp: When the mutation occurred (Date.now())
+         *        - state: The current state object (contains Signals)
+         * @returns {() => void} Unsubscribe function. Call to stop receiving notifications.
+         * @throws {Error} If callback is not a function.
+         * @see dispatch - Triggers mutations that notify subscribers.
          */ subscribe(callback) {
                   if (typeof callback !== "function") {
                       throw new Error("Subscribe callback must be a function");
@@ -2101,20 +2747,32 @@
                   };
               }
               /**
-         * Gets a deep copy of the current state values (not signals)
-         * @returns {Object} The current state values
+         * Gets current state values (not signals).
+         *
+         * @note When persistence include/exclude filters are configured,
+         * this returns only the filtered subset of state.
+         * @returns {Record<string, unknown>} The current state values (filtered by persistence config if set).
+         * @see replaceState - Set state values.
+         * @see subscribe - Listen for state changes.
          */ getState() {
                   return this._extractPersistedData();
               }
               /**
-         * Replaces the entire state (useful for testing or state hydration)
-         * @param {Object} newState - The new state object
+         * Replaces state values (useful for testing or state hydration).
+         *
+         * @note When persistence include/exclude filters are configured,
+         * this only updates the filtered subset of state.
+         * @param {Record<string, unknown>} newState - The new state object.
+         * @returns {void}
+         * @see getState - Get current state values.
          */ replaceState(newState) {
                   this._applyPersistedData(newState);
                   this._saveState();
               }
               /**
-         * Clears persisted state from storage
+         * Clears persisted state from storage.
+         * Does nothing if persistence is disabled or running in SSR.
+         * @returns {void}
          */ clearPersistedState() {
                   if (!this.persistence.enabled || typeof window === "undefined") {
                       return;
@@ -2129,11 +2787,14 @@
                   }
               }
               /**
-         * 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
+         * Registers a new namespaced module at runtime.
+         * Logs a warning if the namespace already exists.
+         * Module state is nested under `state[namespace]` and actions under `actions[namespace]`.
+         * @param {string} namespace - The namespace for the module.
+         * @param {StoreModule} module - The module definition.
+         * @param {Record<string, unknown>} module.state - The module's initial state.
+         * @param {Record<string, ActionFunction>} module.actions - The module's actions.
+         * @returns {void}
          */ registerModule(namespace, module) {
                   if (this.state[namespace] || this.actions[namespace]) {
                       console.warn(`[StorePlugin] Module "${namespace}" already exists`);
@@ -2149,8 +2810,11 @@
                   this._saveState();
               }
               /**
-         * Unregisters a namespaced module
-         * @param {string} namespace - The namespace to unregister
+         * Unregisters a namespaced module.
+         * Logs a warning if the namespace doesn't exist.
+         * Removes both state and actions under the namespace.
+         * @param {string} namespace - The namespace to unregister.
+         * @returns {void}
          */ unregisterModule(namespace) {
                   if (!this.state[namespace] && !this.actions[namespace]) {
                       console.warn(`[StorePlugin] Module "${namespace}" does not exist`);
@@ -2161,10 +2825,11 @@
                   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
+         * Creates a new reactive state property at runtime.
+         *
+         * @param {string} key - The state key.
+         * @param {*} initialValue - The initial value.
+         * @returns {Signal} The created signal, or existing signal if key exists.
          */ createState(key, initialValue) {
                   if (this.state[key]) {
                       return this.state[key]; // Return existing state
@@ -2174,21 +2839,50 @@
                   return this.state[key];
               }
               /**
-         * Creates a new action at runtime
-         * @param {string} name - The action name
-         * @param {Function} actionFn - The action function
+         * Creates a new action at runtime.
+         * Overwrites existing action if name already exists.
+         * Supports dot-notation for namespaced actions (e.g., "auth.login").
+         * @param {string} name - The action name (supports dot notation for namespaces).
+         * @param {ActionFunction} actionFn - The action function (receives state and payload).
+         * @returns {void}
+         * @throws {Error} If actionFn is not a function.
+         * @example
+         * // Root-level action
+         * store.createAction("increment", (state) => state.count.value++);
+         *
+         * // Namespaced action
+         * store.createAction("auth.login", async (state, credentials) => {
+         *   // ... login logic
+         * });
          */ createAction(name, actionFn) {
                   if (typeof actionFn !== "function") {
                       throw new Error("Action must be a function");
                   }
-                  this.actions[name] = actionFn;
+                  // Fast path: no dot means simple action (avoids array allocation)
+                  if (name.indexOf(".") === -1) {
+                      this.actions[name] = actionFn;
+                      return;
+                  }
+                  // Namespaced action, traverse/create nested structure
+                  const parts = name.split(".");
+                  const lastIndex = parts.length - 1;
+                  let current = this.actions;
+                  for(let i = 0; i < lastIndex; i++){
+                      current = current[parts[i]] || (current[parts[i]] = {});
+                  }
+                  current[parts[lastIndex]] = actionFn;
               }
-              constructor(){
-                  this.state = {};
-                  this.actions = {};
-                  this.subscribers = new Set();
-                  this.mutations = [];
-                  this.persistence = {
+              /**
+         * Creates a new Store instance.
+         * Initializes state signals, actions, persistence, and devtools integration.
+         *
+         * @constructor
+         */ constructor(){
+                  /** @type {Record<string, Signal | Record<string, unknown>>} */ this.state = {};
+                  /** @type {Record<string, ActionFunction | Record<string, ActionFunction>>} */ this.actions = {};
+                  /** @type {Set<SubscribeCallback>} */ this.subscribers = new Set();
+                  /** @type {StoreMutation[]} */ this.mutations = [];
+                  /** @type {{enabled: boolean, key: string, storage: string, include: string[]|null, exclude: string[]|null}} */ this.persistence = {
                       enabled: false,
                       key: "eleva-store",
                       storage: "localStorage",
@@ -2196,8 +2890,8 @@
                       exclude: null,
                       ...persistence
                   };
-                  this.devTools = devTools;
-                  this.onError = onError;
+                  /** @type {boolean} */ this.devTools = devTools;
+                  /** @type {((error: Error, context: string) => void)|null} */ this.onError = onError;
                   this._initializeState(state, actions);
                   this._initializeNamespaces(namespaces);
                   this._loadPersistedState();
@@ -2209,7 +2903,13 @@
           // Store the original mount method to override it
           const originalMount = eleva.mount;
           /**
-       * Override the mount method to inject store context into components
+       * Overridden mount method that injects store context into components.
+       * Wraps the original mount to add `ctx.store` to the component's setup context.
+       *
+       * @param {HTMLElement} container - The DOM element where the component will be mounted.
+       * @param {string | ComponentDefinition} compName - Component name or definition.
+       * @param {ComponentProps} [props={}] - Optional properties to pass to the component.
+       * @returns {Promise<MountResult>} The mount result.
        */ eleva.mount = async (container, compName, props = {})=>{
               // Get the component definition
               const componentDef = typeof compName === "string" ? eleva._components.get(compName) || compName : compName;
@@ -2220,8 +2920,7 @@
               const wrappedComponent = {
                   ...componentDef,
                   async setup (ctx) {
-                      // Inject store into the context with enhanced API
-                      ctx.store = {
+                      /** @type {StoreApi} */ ctx.store = {
                           // Core store functionality
                           state: store.state,
                           dispatch: store.dispatch.bind(store),
@@ -2247,7 +2946,16 @@
           };
           // Override _mountComponents to ensure child components also get store context
           const originalMountComponents = eleva._mountComponents;
-          eleva._mountComponents = async (container, children, childInstances)=>{
+          /**
+       * Overridden _mountComponents method that injects store context into child components.
+       * Wraps each child component's setup function to add `ctx.store` before mounting.
+       *
+       * @param {HTMLElement} container - The parent container element.
+       * @param {ChildrenMap} children - Map of selectors to component definitions.
+       * @param {MountResult[]} childInstances - Array to store mounted instances.
+       * @param {ComponentContext & SetupResult} context - Parent component context.
+       * @returns {Promise<void>}
+       */ eleva._mountComponents = async (container, children, childInstances, context)=>{
               // Create wrapped children with store injection
               const wrappedChildren = {};
               for (const [selector, childComponent] of Object.entries(children)){
@@ -2256,8 +2964,7 @@
                       wrappedChildren[selector] = {
                           ...componentDef,
                           async setup (ctx) {
-                              // Inject store into the context with enhanced API
-                              ctx.store = {
+                              /** @type {StoreApi} */ ctx.store = {
                                   // Core store functionality
                                   state: store.state,
                                   dispatch: store.dispatch.bind(store),
@@ -2283,23 +2990,23 @@
                   }
               }
               // Call original _mountComponents with wrapped children
-              return await originalMountComponents.call(eleva, container, wrappedChildren, childInstances);
+              return await originalMountComponents.call(eleva, container, wrappedChildren, childInstances, context);
           };
           // Expose store instance and utilities on the Eleva instance
-          eleva.store = store;
+          /** @type {StoreApi} */ eleva.store = store;
           /**
-       * Expose utility methods on the Eleva instance
-       * @namespace eleva.store
-       */ eleva.createAction = (name, actionFn)=>{
-              store.actions[name] = actionFn;
+       * Expose utility methods on the Eleva instance.
+       * These are top-level helpers (e.g., `eleva.dispatch`) in addition to `eleva.store`.
+       */ /** @type {(name: string, actionFn: ActionFunction) => void} */ eleva.createAction = (name, actionFn)=>{
+              store.createAction(name, actionFn);
           };
-          eleva.dispatch = (actionName, payload)=>{
+          /** @type {DispatchFunction} */ eleva.dispatch = (actionName, payload)=>{
               return store.dispatch(actionName, payload);
           };
-          eleva.getState = ()=>{
+          /** @type {() => Record<string, unknown>} */ eleva.getState = ()=>{
               return store.getState();
           };
-          eleva.subscribe = (callback)=>{
+          /** @type {(callback: SubscribeCallback) => () => void} */ eleva.subscribe = (callback)=>{
               return store.subscribe(callback);
           };
           // Store original methods for cleanup
@@ -2307,14 +3014,17 @@
           eleva._originalMountComponents = originalMountComponents;
       },
       /**
-     * Uninstalls the plugin from the Eleva instance
-     *
-     * @param {Object} eleva - The Eleva instance
+     * Uninstalls the plugin from the Eleva instance.
      *
+     * @public
+     * @param {Eleva} eleva - The Eleva instance.
+     * @returns {void}
      * @description
      * Restores the original Eleva methods and removes all plugin-specific
      * functionality. This method should be called when the plugin is no
      * longer needed.
+     * Also removes `eleva.store` and top-level helpers (`eleva.dispatch`,
+     * `eleva.getState`, `eleva.subscribe`, `eleva.createAction`).
      *
      * @example
      * // Uninstall the plugin