import { Router } from '../types/router';
/**
 * Enhances a router with plugin management capabilities.
 *
 * This module provides functionality to:
 * - Register and manage plugins
 * - Automatically bind plugin lifecycle methods to router events
 * - Handle plugin teardown and cleanup
 * - Support dependency injection for plugins
 *
 * Plugins can define lifecycle methods that automatically get called:
 * - onStart: When router starts
 * - onStop: When router stops
 * - onTransitionStart: When navigation begins
 * - onTransitionSuccess: When navigation succeeds
 * - onTransitionError: When navigation fails
 * - onTransitionCancel: When navigation is cancelled
 * - teardown: For plugin cleanup
 *
 * @template Dependencies - Type of dependencies available to plugins
 * @param router - Router instance to enhance with plugin capabilities
 * @returns Enhanced router with plugin functionality
 *
 * @example
 * ```typescript
 * // Logger plugin
 * const loggerPlugin = (router, deps) => ({
 *   onTransitionStart: (toState, fromState) => {
 *     console.log(`Starting navigation to ${toState.name}`)
 *   },
 *   onTransitionSuccess: (toState, fromState) => {
 *     console.log(`Successfully navigated to ${toState.name}`)
 *   },
 *   teardown: () => {
 *     console.log('Logger plugin cleaned up')
 *   }
 * })
 *
 * // Analytics plugin
 * const analyticsPlugin = (router, deps) => ({
 *   onTransitionSuccess: (toState) => {
 *     deps.analytics.track('page_view', { page: toState.name })
 *   }
 * })
 *
 * const unregister = router.usePlugin(loggerPlugin, analyticsPlugin)
 *
 * // Later, remove plugins
 * unregister()
 * ```
 */
export default function withPlugins<Dependencies>(router: Router<Dependencies>): Router<Dependencies>;