eleva 1.0.1 → 1.1.0

package/dist/plugins/router.umd.js

@@ -1,4 +1,4 @@
-/*! Eleva Router Plugin v1.0.1 | MIT License | https://elevajs.com */
+/*! Eleva Router Plugin v1.1.0 | MIT License | https://elevajs.com */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
   typeof define === 'function' && define.amd ? define(['exports'], factory) :
@@ -6,60 +6,176 @@
 })(this, (function (exports) { 'use strict';
 
   /**
+   * @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
@@ -70,76 +186,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}`;
@@ -158,7 +317,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);
       },
@@ -166,7 +325,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,
@@ -175,26 +334,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
@@ -206,9 +376,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
@@ -217,11 +390,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 = {
@@ -234,57 +412,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 }
@@ -300,10 +514,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.
    *
@@ -329,15 +543,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
@@ -412,7 +626,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") {
@@ -456,6 +670,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
@@ -500,8 +719,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
@@ -525,6 +747,7 @@
       /**
      * Alias for destroy(). Stops the router and cleans up all resources.
      * Provided for semantic consistency (start/stop pattern).
+     * @async
      * @returns {Promise<void>}
      *
      * @example
@@ -536,9 +759,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
@@ -601,7 +828,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;
           }
       }
@@ -621,7 +848,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;
@@ -631,7 +858,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)){
@@ -643,8 +879,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 {
@@ -663,26 +903,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("?");
@@ -702,7 +946,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;
               }
           }
@@ -789,7 +1033,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
@@ -811,7 +1055,7 @@
                   to,
                   from
               });
-              await this.emitter.emit("router:onError", error, to, from);
+              await this.emitter.emit("router:error", error, to, from);
               return false;
           }
       }
@@ -827,7 +1071,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 = {
@@ -888,7 +1133,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) {
@@ -907,7 +1153,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) {
@@ -926,7 +1172,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) {
@@ -948,8 +1194,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 {
@@ -975,9 +1223,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) {
@@ -1001,8 +1264,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;
       }
@@ -1017,7 +1280,7 @@
           return {
               ...component,
               async setup (ctx) {
-                  ctx.router = {
+                  /** @type {RouterContext} */ ctx.router = {
                       navigate: self.navigate.bind(self),
                       current: self.currentRoute,
                       previous: self.previousRoute,
@@ -1044,9 +1307,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
@@ -1103,7 +1370,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) {
@@ -1155,10 +1430,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
@@ -1206,6 +1483,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');
@@ -1293,6 +1571,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);
       }
@@ -1300,6 +1579,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);
       }
@@ -1307,6 +1587,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);
       }
@@ -1314,12 +1595,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", {
@@ -1368,7 +1655,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;
@@ -1380,6 +1669,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 = {
@@ -1389,40 +1679,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:
@@ -1461,7 +1741,7 @@
       /**
      * Plugin version
      * @type {string}
-     */ version: "1.0.1",
+     */ version: "1.1.0",
       /**
      * Plugin description
      * @type {string}
@@ -1469,16 +1749,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
@@ -1508,9 +1797,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) {
@@ -1534,7 +1824,7 @@
               }
           });
           const router = new Router(eleva, options);
-          eleva.router = router;
+          /** @type {Router} */ eleva.router = router;
           if (options.autoStart !== false) {
               queueMicrotask(()=>router.start());
           }
@@ -1549,16 +1839,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();