eleva 1.0.1 → 1.1.0

package/dist/{eleva-plugins.cjs.js → eleva-plugins.cjs}

@@ -1,7 +1,38 @@
-/*! Eleva Plugins v1.0.1 | MIT License | https://elevajs.com */
+/*! Eleva Plugins v1.1.0 | MIT License | https://elevajs.com */
 '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}
@@ -42,33 +73,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;
@@ -139,8 +213,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) {
@@ -164,12 +244,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) {
@@ -186,60 +275,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
@@ -250,76 +455,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}`;
@@ -338,7 +586,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);
     },
@@ -346,7 +594,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,
@@ -355,26 +603,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
@@ -386,9 +645,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
@@ -397,11 +659,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 = {
@@ -414,57 +681,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 }
@@ -480,10 +783,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.
  *
@@ -509,15 +812,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
@@ -592,7 +895,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") {
@@ -636,6 +939,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
@@ -680,8 +988,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
@@ -705,6 +1016,7 @@
     /**
    * Alias for destroy(). Stops the router and cleans up all resources.
    * Provided for semantic consistency (start/stop pattern).
+   * @async
    * @returns {Promise<void>}
    *
    * @example
@@ -716,9 +1028,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
@@ -781,7 +1097,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;
         }
     }
@@ -801,7 +1117,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;
@@ -811,7 +1127,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)){
@@ -823,8 +1148,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 {
@@ -843,26 +1172,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("?");
@@ -882,7 +1215,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;
             }
         }
@@ -969,7 +1302,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
@@ -991,7 +1324,7 @@
                 to,
                 from
             });
-            await this.emitter.emit("router:onError", error, to, from);
+            await this.emitter.emit("router:error", error, to, from);
             return false;
         }
     }
@@ -1007,7 +1340,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 = {
@@ -1068,7 +1402,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) {
@@ -1087,7 +1422,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) {
@@ -1106,7 +1441,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) {
@@ -1128,8 +1463,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 {
@@ -1155,9 +1492,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) {
@@ -1181,8 +1533,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;
     }
@@ -1197,7 +1549,7 @@
         return {
             ...component,
             async setup (ctx) {
-                ctx.router = {
+                /** @type {RouterContext} */ ctx.router = {
                     navigate: self.navigate.bind(self),
                     current: self.currentRoute,
                     previous: self.previousRoute,
@@ -1224,9 +1576,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
@@ -1283,7 +1639,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) {
@@ -1335,10 +1699,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
@@ -1386,6 +1752,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');
@@ -1473,6 +1840,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);
     }
@@ -1480,6 +1848,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);
     }
@@ -1487,6 +1856,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);
     }
@@ -1494,12 +1864,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", {
@@ -1548,7 +1924,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;
@@ -1560,6 +1938,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 = {
@@ -1569,40 +1948,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:
@@ -1641,7 +2010,7 @@
     /**
    * Plugin version
    * @type {string}
-   */ version: "1.0.1",
+   */ version: "1.1.0",
     /**
    * Plugin description
    * @type {string}
@@ -1649,16 +2018,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
@@ -1688,9 +2066,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) {
@@ -1714,7 +2093,7 @@
             }
         });
         const router = new Router(eleva, options);
-        eleva.router = router;
+        /** @type {Router} */ eleva.router = router;
         if (options.autoStart !== false) {
             queueMicrotask(()=>router.start());
         }
@@ -1729,16 +2108,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();
@@ -1757,6 +2142,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,
@@ -1783,7 +2356,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: {
@@ -1806,7 +2379,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>
  *   `
  * });
@@ -1818,27 +2391,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
@@ -1858,12 +2438,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;
    *         }
    *       }
    *     }
@@ -1876,12 +2456,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])=>{
@@ -1893,8 +2479,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;
@@ -1916,8 +2506,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;
@@ -1938,8 +2532,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;
@@ -1955,8 +2555,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) {
@@ -1968,8 +2572,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;
@@ -1987,8 +2595,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])=>{
@@ -2009,8 +2622,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;
@@ -2018,10 +2635,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);
@@ -2069,8 +2702,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;
@@ -2083,9 +2720,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");
@@ -2097,20 +2743,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;
@@ -2125,11 +2783,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`);
@@ -2145,8 +2806,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`);
@@ -2157,10 +2821,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
@@ -2170,21 +2835,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",
@@ -2192,8 +2886,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();
@@ -2205,7 +2899,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;
@@ -2216,8 +2916,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),
@@ -2243,7 +2942,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)){
@@ -2252,8 +2960,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),
@@ -2279,23 +2986,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
@@ -2303,14 +3010,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
@@ -2348,4 +3058,4 @@
 exports.Attr = AttrPlugin;
 exports.Router = RouterPlugin;
 exports.Store = StorePlugin;
-//# sourceMappingURL=eleva-plugins.cjs.js.map
+//# sourceMappingURL=eleva-plugins.cjs.map