sibujs 1.0.0-beta.1

package/dist/src/plugins/router.js

@@ -0,0 +1,1178 @@
+import { useState } from "../core/useState";
+import { track } from "../reactivity/track";
+// ============================================================================
+// UTILITY CLASSES
+// ============================================================================
+/**
+ * LRU Cache implementation with automatic cleanup
+ */
+class LRUCache {
+    constructor(maxSize = 100) {
+        this.cache = new Map();
+        this.maxSize = Math.max(1, maxSize);
+    }
+    get(key) {
+        const value = this.cache.get(key);
+        if (value !== undefined) {
+            // Move to end (most recently used)
+            this.cache.delete(key);
+            this.cache.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        if (this.cache.has(key)) {
+            this.cache.delete(key);
+        }
+        else if (this.cache.size >= this.maxSize) {
+            // Remove least recently used
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(key, value);
+    }
+    has(key) {
+        return this.cache.has(key);
+    }
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+/**
+ * Navigation controller for handling concurrent navigation attempts
+ */
+class NavigationController {
+    constructor() {
+        this.currentController = null;
+    }
+    async navigate(navigationFn) {
+        // Cancel current navigation
+        if (this.currentController) {
+            this.currentController.abort();
+        }
+        this.currentController = new AbortController();
+        const signal = this.currentController.signal;
+        try {
+            await navigationFn(signal);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                // Navigation was cancelled, this is expected
+                return;
+            }
+            throw error;
+        }
+        finally {
+            if (this.currentController?.signal === signal) {
+                this.currentController = null;
+            }
+        }
+    }
+    abort() {
+        if (this.currentController) {
+            this.currentController.abort();
+            this.currentController = null;
+        }
+    }
+    get isNavigating() {
+        return this.currentController !== null;
+    }
+}
+/**
+ * Enhanced route matcher with trie optimization
+ */
+class RouteMatcher {
+    constructor(routes) {
+        this.routeTrie = new Map();
+        this.namedRoutes = new Map();
+        this.compiledPatterns = new LRUCache(50);
+        this.buildIndex(routes);
+    }
+    buildIndex(routes, parentPath = '') {
+        for (const route of routes) {
+            const fullPath = parentPath + route.path;
+            // Index by path
+            this.routeTrie.set(fullPath, route);
+            // Index by name
+            if (route.name) {
+                this.namedRoutes.set(route.name, route);
+            }
+            // Handle aliases
+            if (route.alias) {
+                const aliases = Array.isArray(route.alias) ? route.alias : [route.alias];
+                for (const alias of aliases) {
+                    this.routeTrie.set(parentPath + alias, route);
+                }
+            }
+            // Index children
+            if (route.children?.length) {
+                this.buildIndex(route.children, fullPath);
+            }
+        }
+    }
+    match(path) {
+        // Try exact match first
+        const exactMatch = this.routeTrie.get(path);
+        if (exactMatch) {
+            return { route: exactMatch, params: {}, matched: [exactMatch] };
+        }
+        // Try pattern matching
+        for (const [routePath, route] of this.routeTrie) {
+            const match = this.matchPattern(path, routePath);
+            if (match) {
+                return { route, params: match.params, matched: [route] };
+            }
+        }
+        return null;
+    }
+    findByName(name) {
+        return this.namedRoutes.get(name) || null;
+    }
+    matchPattern(path, routePath) {
+        // Handle wildcard routes
+        if (routePath === '*' || routePath.endsWith('/*')) {
+            const basePath = routePath.slice(0, -2);
+            if (path.startsWith(basePath)) {
+                return { params: { pathMatch: path.slice(basePath.length) } };
+            }
+            return null;
+        }
+        // Get or compile pattern
+        let compiled = this.compiledPatterns.get(routePath);
+        if (!compiled) {
+            compiled = this.compileRoute(routePath);
+            this.compiledPatterns.set(routePath, compiled);
+        }
+        const match = path.match(compiled.regex);
+        if (match) {
+            const params = {};
+            compiled.keys.forEach((key, i) => {
+                if (match[i + 1] !== undefined) {
+                    params[key] = decodeURIComponent(match[i + 1]);
+                }
+            });
+            return { params };
+        }
+        return null;
+    }
+    compileRoute(routePath) {
+        const keys = [];
+        // Handle optional parameters: /users/:id?
+        let pattern = routePath.replace(/\/:[^/]+\?/g, '(?:/([^/]+))?');
+        // Handle regular parameters: /users/:id
+        pattern = pattern.replace(/:([^/]+)/g, (match, key) => {
+            keys.push(key);
+            return '([^/]+)';
+        });
+        return {
+            regex: new RegExp(`^${pattern}$`),
+            keys
+        };
+    }
+    rebuild(routes) {
+        this.routeTrie.clear();
+        this.namedRoutes.clear();
+        this.compiledPatterns.clear();
+        this.buildIndex(routes);
+    }
+}
+/**
+ * Guard manager with timeout and error handling
+ */
+class GuardManager {
+    constructor(timeout = 5000) {
+        this.beforeEachGuards = [];
+        this.beforeResolveGuards = [];
+        this.afterEachHooks = [];
+        this.timeout = timeout;
+    }
+    async runBeforeEach(to, from, signal) {
+        for (const guard of this.beforeEachGuards) {
+            if (signal.aborted)
+                throw new Error('Navigation aborted');
+            const result = await this.runGuard(guard, to, from, signal);
+            if (result !== true)
+                return result;
+        }
+        return true;
+    }
+    async runBeforeResolve(to, from, signal) {
+        for (const guard of this.beforeResolveGuards) {
+            if (signal.aborted)
+                throw new Error('Navigation aborted');
+            const result = await this.runGuard(guard, to, from, signal);
+            if (result !== true)
+                return result;
+        }
+        return true;
+    }
+    runAfterEach(to, from) {
+        for (const hook of this.afterEachHooks) {
+            try {
+                hook(to, from);
+            }
+            catch (error) {
+                console.error('[Router] AfterEach hook error:', error);
+            }
+        }
+    }
+    runGuard(guard, to, from, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal.aborted) {
+                reject(new Error('Navigation aborted'));
+                return;
+            }
+            let resolved = false;
+            const next = (result) => {
+                if (resolved || signal.aborted)
+                    return;
+                resolved = true;
+                if (result instanceof Error) {
+                    reject(result);
+                }
+                else if (result === false) {
+                    resolve(false);
+                }
+                else if (typeof result === 'string') {
+                    resolve(result);
+                }
+                else {
+                    resolve(true);
+                }
+            };
+            // Set up abort handler
+            const abortHandler = () => {
+                if (!resolved) {
+                    resolved = true;
+                    reject(new Error('Navigation aborted'));
+                }
+            };
+            signal.addEventListener('abort', abortHandler);
+            // Set up timeout
+            const timeoutId = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    signal.removeEventListener('abort', abortHandler);
+                    reject(new Error('Guard timeout'));
+                }
+            }, this.timeout);
+            try {
+                guard(to, from, next);
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                signal.removeEventListener('abort', abortHandler);
+                if (!resolved) {
+                    resolved = true;
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+            // Cleanup when resolved
+            Promise.resolve().then(() => {
+                if (resolved) {
+                    clearTimeout(timeoutId);
+                    signal.removeEventListener('abort', abortHandler);
+                }
+            });
+        });
+    }
+    addBeforeEach(guard) {
+        this.beforeEachGuards.push(guard);
+        return () => {
+            const index = this.beforeEachGuards.indexOf(guard);
+            if (index > -1)
+                this.beforeEachGuards.splice(index, 1);
+        };
+    }
+    addBeforeResolve(guard) {
+        this.beforeResolveGuards.push(guard);
+        return () => {
+            const index = this.beforeResolveGuards.indexOf(guard);
+            if (index > -1)
+                this.beforeResolveGuards.splice(index, 1);
+        };
+    }
+    addAfterEach(hook) {
+        this.afterEachHooks.push(hook);
+        return () => {
+            const index = this.afterEachHooks.indexOf(hook);
+            if (index > -1)
+                this.afterEachHooks.splice(index, 1);
+        };
+    }
+    clear() {
+        this.beforeEachGuards = [];
+        this.beforeResolveGuards = [];
+        this.afterEachHooks = [];
+    }
+}
+/**
+ * Component loader with caching and error recovery
+ */
+class ComponentLoader {
+    constructor(cacheSize = 50, retryDelay = 1000) {
+        this.errorCache = new Map();
+        this.loadingPromises = new Map();
+        this.componentCache = new LRUCache(cacheSize);
+        this.retryDelay = retryDelay;
+    }
+    async loadComponent(route, routePath) {
+        if (!('component' in route)) {
+            throw new Error(`Route ${routePath} does not have a component`);
+        }
+        const comp = route.component;
+        // Return cached component
+        const cached = this.componentCache.get(routePath);
+        if (cached)
+            return cached;
+        // Check if there's already a loading promise
+        const existingPromise = this.loadingPromises.get(routePath);
+        if (existingPromise)
+            return existingPromise;
+        // Check error cache
+        const errorInfo = this.errorCache.get(routePath);
+        if (errorInfo && Date.now() - errorInfo.timestamp < this.retryDelay) {
+            throw new Error(`Component loading failed recently, retry in ${this.retryDelay}ms`);
+        }
+        // Create loading promise
+        const loadingPromise = this.doLoadComponent(comp, routePath);
+        this.loadingPromises.set(routePath, loadingPromise);
+        try {
+            const component = await loadingPromise;
+            this.componentCache.set(routePath, component);
+            this.errorCache.delete(routePath); // Clear error on success
+            return component;
+        }
+        catch (error) {
+            // Update error cache
+            const currentError = this.errorCache.get(routePath) || { timestamp: 0, count: 0 };
+            this.errorCache.set(routePath, {
+                timestamp: Date.now(),
+                count: currentError.count + 1
+            });
+            throw error;
+        }
+        finally {
+            this.loadingPromises.delete(routePath);
+        }
+    }
+    async doLoadComponent(comp, routePath) {
+        // Synchronous component
+        if (!this.isAsyncComponent(comp)) {
+            const result = comp();
+            if (!this.isHTMLElement(result)) {
+                throw new Error(`Component for route "${routePath}" must return HTMLElement, got ${typeof result}`);
+            }
+            return comp;
+        }
+        // Async component
+        try {
+            const result = await comp();
+            const component = this.extractComponent(result, routePath);
+            // Validate component
+            const testElement = component();
+            if (!this.isHTMLElement(testElement)) {
+                throw new Error(`Component for route "${routePath}" must return HTMLElement, got ${typeof testElement}`);
+            }
+            return component;
+        }
+        catch (error) {
+            throw new Error(`Failed to load component for route "${routePath}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    isAsyncComponent(comp) {
+        return comp.constructor.name === 'AsyncFunction' ||
+            (typeof comp === 'function' && comp.toString().includes('import('));
+    }
+    isHTMLElement(value) {
+        return value instanceof HTMLElement;
+    }
+    extractComponent(result, routePath) {
+        if ('default' in result && typeof result.default === 'function') {
+            return result.default;
+        }
+        if (typeof result === 'function') {
+            return result;
+        }
+        if (this.isHTMLElement(result)) {
+            return () => result;
+        }
+        throw new Error(`Invalid component module for route "${routePath}"`);
+    }
+    clearErrors() {
+        this.errorCache.clear();
+    }
+    clearCache() {
+        this.componentCache.clear();
+        this.errorCache.clear();
+        this.loadingPromises.clear();
+    }
+}
+// ============================================================================
+// MAIN ROUTER CLASS
+// ============================================================================
+export class SibuRouter {
+    constructor(routes, options = {}) {
+        // Event listeners cleanup
+        this.cleanup = [];
+        this.options = {
+            mode: 'history',
+            base: '',
+            linkActiveClass: 'router-link-active',
+            linkExactActiveClass: 'router-link-exact-active',
+            fallback: true,
+            guardTimeout: 5000,
+            cacheSize: 50,
+            errorRetryDelay: 1000,
+            preloadStrategy: 'none',
+            ...options
+        };
+        // Initialize state properly
+        const [currentRouteState, setCurrentRouteState] = useState(this.createInitialRoute());
+        const [isReadyState, setIsReadyState] = useState(false);
+        this.currentRouteGetter = currentRouteState;
+        this.currentRouteSetter = setCurrentRouteState;
+        this.isReadyGetter = isReadyState;
+        this.isReadySetter = setIsReadyState;
+        this.matcher = new RouteMatcher(routes);
+        this.guards = new GuardManager(this.options.guardTimeout);
+        this.loader = new ComponentLoader(this.options.cacheSize, this.options.errorRetryDelay);
+        this.navigator = new NavigationController();
+        this.initialize();
+    }
+    initialize() {
+        // Set up event listeners
+        if (this.options.mode === 'history') {
+            const popstateHandler = () => this.handleLocationChange();
+            window.addEventListener('popstate', popstateHandler);
+            this.cleanup.push(() => window.removeEventListener('popstate', popstateHandler));
+        }
+        else {
+            const hashHandler = () => this.handleLocationChange();
+            window.addEventListener('hashchange', hashHandler);
+            this.cleanup.push(() => window.removeEventListener('hashchange', hashHandler));
+        }
+        // Set initial route
+        queueMicrotask(() => {
+            this.handleLocationChange();
+            this.isReadySetter(true);
+        });
+    }
+    createInitialRoute() {
+        return {
+            path: '/',
+            params: {},
+            query: {},
+            hash: '',
+            meta: {},
+            matched: []
+        };
+    }
+    handleLocationChange() {
+        const path = this.getCurrentPath();
+        const context = this.createRouteContext(path);
+        this.currentRouteSetter(context);
+    }
+    getCurrentPath() {
+        const { mode, base } = this.options;
+        if (mode === 'hash') {
+            return window.location.hash.slice(1) || '/';
+        }
+        let path = window.location.pathname;
+        if (base && path.startsWith(base)) {
+            path = path.slice(base.length);
+        }
+        return (path || '/') + window.location.search + window.location.hash;
+    }
+    createRouteContext(fullPath) {
+        const [pathWithQuery, hash = ''] = fullPath.split('#');
+        const [path, queryString = ''] = pathWithQuery.split('?');
+        const query = Object.fromEntries(new URLSearchParams(queryString));
+        const match = this.matcher.match(path || '/');
+        const params = match?.params || {};
+        const meta = match?.route.meta || {};
+        const matched = match ? [match.route] : [];
+        return {
+            path: path || '/',
+            params,
+            query,
+            hash,
+            meta,
+            matched
+        };
+    }
+    // Public API
+    async navigate(to, options = {}) {
+        try {
+            const result = await this.navigator.navigate(async (signal) => {
+                const targetPath = this.resolvePath(to);
+                const from = this.currentRouteGetter();
+                const toContext = this.createRouteContext(targetPath);
+                // Check for duplicate navigation
+                if (this.isSameRoute(from, toContext)) {
+                    throw new NavigationFailureError('duplicated', from, toContext);
+                }
+                await this.performNavigation(toContext, from, options, signal);
+            });
+            return { success: true, route: this.currentRouteGetter() };
+        }
+        catch (error) {
+            if (error instanceof NavigationFailureError) {
+                return { success: false, failure: error.toFailure() };
+            }
+            const failure = {
+                type: 'aborted',
+                from: this.currentRouteGetter(),
+                to: this.createRouteContext(this.resolvePath(to)),
+                error: error instanceof Error ? error : new Error(String(error))
+            };
+            return { success: false, failure };
+        }
+    }
+    async performNavigation(to, from, options, signal) {
+        // Run beforeEach guards
+        const beforeEachResult = await this.guards.runBeforeEach(to, from, signal);
+        if (beforeEachResult !== true) {
+            if (typeof beforeEachResult === 'string') {
+                return this.performNavigation(this.createRouteContext(beforeEachResult), from, options, signal);
+            }
+            throw new NavigationFailureError('aborted', from, to);
+        }
+        // Handle route-specific logic
+        const match = this.matcher.match(to.path);
+        if (match) {
+            const { route } = match;
+            // Run beforeEnter guards
+            if ('beforeEnter' in route && route.beforeEnter) {
+                const guards = Array.isArray(route.beforeEnter) ? route.beforeEnter : [route.beforeEnter];
+                for (const guard of guards) {
+                    if (signal.aborted)
+                        throw new Error('Navigation aborted');
+                    const result = await guard(to, from);
+                    if (result !== true) {
+                        if (typeof result === 'string') {
+                            return this.performNavigation(this.createRouteContext(result), from, options, signal);
+                        }
+                        throw new NavigationFailureError('aborted', from, to);
+                    }
+                }
+            }
+            // Handle redirects
+            if ('redirect' in route) {
+                const redirectPath = typeof route.redirect === 'function'
+                    ? route.redirect(to)
+                    : route.redirect;
+                return this.performNavigation(this.createRouteContext(redirectPath), from, options, signal);
+            }
+        }
+        // Run beforeResolve guards
+        const beforeResolveResult = await this.guards.runBeforeResolve(to, from, signal);
+        if (beforeResolveResult !== true) {
+            if (typeof beforeResolveResult === 'string') {
+                return this.performNavigation(this.createRouteContext(beforeResolveResult), from, options, signal);
+            }
+            throw new NavigationFailureError('aborted', from, to);
+        }
+        // Update browser history
+        this.updateHistory(to, options);
+        // Update current route
+        this.currentRouteSetter(to);
+        // Run afterEach hooks
+        this.guards.runAfterEach(to, from);
+        // Handle scroll behavior
+        this.handleScrollBehavior(to, from);
+    }
+    resolvePath(to) {
+        if (typeof to === 'string')
+            return to;
+        let path = to.path || '';
+        // Handle named routes
+        if (to.name && !path) {
+            const namedRoute = this.matcher.findByName(to.name);
+            if (namedRoute) {
+                path = namedRoute.path;
+            }
+        }
+        // Replace parameters
+        if (to.params) {
+            for (const [key, value] of Object.entries(to.params)) {
+                path = path.replace(`:${key}`, encodeURIComponent(value));
+            }
+        }
+        // Add query parameters
+        if (to.query && Object.keys(to.query).length > 0) {
+            path += '?' + new URLSearchParams(to.query).toString();
+        }
+        // Add hash
+        if (to.hash) {
+            path += '#' + to.hash;
+        }
+        return path;
+    }
+    isSameRoute(from, to) {
+        return from.path === to.path &&
+            JSON.stringify(from.params) === JSON.stringify(to.params) &&
+            JSON.stringify(from.query) === JSON.stringify(to.query) &&
+            from.hash === to.hash;
+    }
+    updateHistory(to, options) {
+        const fullPath = this.options.base + to.path +
+            (Object.keys(to.query).length ? '?' + new URLSearchParams(to.query).toString() : '') +
+            (to.hash ? '#' + to.hash : '');
+        if (options.replace) {
+            history.replaceState(options.state || {}, '', fullPath);
+        }
+        else {
+            history.pushState(options.state || {}, '', fullPath);
+        }
+    }
+    handleScrollBehavior(to, from) {
+        if (this.options.scrollBehavior) {
+            const scrollTo = this.options.scrollBehavior(to, from, null);
+            if (scrollTo) {
+                requestAnimationFrame(() => {
+                    window.scrollTo(scrollTo.x, scrollTo.y);
+                });
+            }
+        }
+    }
+    // Component loading
+    async loadComponent(route, routePath) {
+        return this.loader.loadComponent(route, routePath);
+    }
+    // Guards API
+    beforeEach(guard) {
+        return this.guards.addBeforeEach(guard);
+    }
+    beforeResolve(guard) {
+        return this.guards.addBeforeResolve(guard);
+    }
+    afterEach(hook) {
+        return this.guards.addAfterEach(hook);
+    }
+    // Utility methods
+    push(to) {
+        return this.navigate(to);
+    }
+    replace(to) {
+        return this.navigate(to, { replace: true });
+    }
+    go(delta) {
+        history.go(delta);
+    }
+    back() {
+        history.back();
+    }
+    forward() {
+        history.forward();
+    }
+    // State getters
+    get currentRoute() {
+        return this.currentRouteGetter();
+    }
+    get isReady() {
+        return this.isReadyGetter();
+    }
+    get isNavigating() {
+        return this.navigator.isNavigating;
+    }
+    // Cleanup
+    destroy() {
+        this.navigator.abort();
+        this.cleanup.forEach(fn => fn());
+        this.cleanup = [];
+        this.guards.clear();
+        this.loader.clearCache();
+        this.isReadySetter(false);
+    }
+    // Cache management
+    clearCache() {
+        this.loader.clearCache();
+    }
+    clearErrorCache() {
+        this.loader.clearErrors();
+    }
+    // Route management
+    updateRoutes(routes) {
+        this.matcher.rebuild(routes);
+        this.clearCache();
+    }
+}
+// ============================================================================
+// NAVIGATION FAILURE CLASS
+// ============================================================================
+class NavigationFailureError extends Error {
+    constructor(type, from, to, error) {
+        super(`Navigation ${type}: from ${from.path} to ${to.path}`);
+        this.type = type;
+        this.from = from;
+        this.to = to;
+        this.name = 'NavigationFailureError';
+        if (error) {
+            this.cause = error;
+        }
+    }
+    toFailure() {
+        return {
+            type: this.type,
+            from: this.from,
+            to: this.to,
+            error: this.cause instanceof Error ? this.cause : undefined
+        };
+    }
+}
+// ============================================================================
+// GLOBAL ROUTER INSTANCE (for compatibility)
+// ============================================================================
+let globalRouter = null;
+export function createRouter(routes, options = {}) {
+    if (globalRouter) {
+        globalRouter.destroy();
+    }
+    globalRouter = new SibuRouter(routes, options);
+    return globalRouter;
+}
+// ============================================================================
+// COMPATIBILITY API (uses global router instance)
+// ============================================================================
+export function useRoute() {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    return globalRouter.currentRoute;
+}
+export function useRouter() {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    return {
+        currentRoute: globalRouter.currentRoute,
+        isReady: globalRouter.isReady,
+        isNavigating: globalRouter.isNavigating,
+        push: (to) => globalRouter.push(to),
+        replace: (to) => globalRouter.replace(to),
+        go: (delta) => globalRouter.go(delta),
+        back: () => globalRouter.back(),
+        forward: () => globalRouter.forward(),
+        beforeEach: (guard) => globalRouter.beforeEach(guard),
+        beforeResolve: (guard) => globalRouter.beforeResolve(guard),
+        afterEach: (hook) => globalRouter.afterEach(hook),
+    };
+}
+export function navigate(to, options) {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    return globalRouter.navigate(to, options);
+}
+export function push(to) {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    return globalRouter.push(to);
+}
+export function replace(to) {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    return globalRouter.replace(to);
+}
+export function go(delta) {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    globalRouter.go(delta);
+}
+export function back() {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    globalRouter.back();
+}
+export function forward() {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    globalRouter.forward();
+}
+export function beforeEach(guard) {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    return globalRouter.beforeEach(guard);
+}
+export function beforeResolve(guard) {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    return globalRouter.beforeResolve(guard);
+}
+export function afterEach(hook) {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    return globalRouter.afterEach(hook);
+}
+// ============================================================================
+// ROUTE COMPONENT
+// ============================================================================
+export function Route() {
+    const anchor = document.createComment("route-outlet");
+    let currentNode = null;
+    let loadingNode = null;
+    let errorNode = null;
+    let isUpdating = false;
+    let currentPath = '';
+    const cleanupNodes = () => {
+        [currentNode, loadingNode, errorNode].forEach(node => {
+            if (node?.parentNode) {
+                node.parentNode.removeChild(node);
+            }
+        });
+        currentNode = null;
+        loadingNode = null;
+        errorNode = null;
+    };
+    const showLoading = () => {
+        if (!loadingNode && anchor.parentNode) {
+            loadingNode = document.createElement('div');
+            loadingNode.className = 'route-loading';
+            loadingNode.setAttribute('role', 'status');
+            loadingNode.setAttribute('aria-label', 'Loading route');
+            const spinner = document.createElement('div');
+            spinner.className = 'route-loading-spinner';
+            spinner.setAttribute('aria-hidden', 'true');
+            const text = document.createElement('span');
+            text.textContent = 'Loading...';
+            text.className = 'route-loading-text';
+            loadingNode.appendChild(spinner);
+            loadingNode.appendChild(text);
+            anchor.parentNode.insertBefore(loadingNode, anchor.nextSibling);
+        }
+    };
+    const hideLoading = () => {
+        if (loadingNode?.parentNode) {
+            loadingNode.parentNode.removeChild(loadingNode);
+            loadingNode = null;
+        }
+    };
+    const showError = (error) => {
+        if (!anchor.parentNode)
+            return;
+        cleanupNodes();
+        errorNode = document.createElement('div');
+        errorNode.className = 'route-error';
+        errorNode.setAttribute('role', 'alert');
+        errorNode.setAttribute('aria-live', 'assertive');
+        // SECURITY FIX: Use textContent instead of innerHTML to prevent XSS
+        const title = document.createElement('h3');
+        title.textContent = 'Route Error';
+        title.className = 'route-error-title';
+        const message = document.createElement('p');
+        message.textContent = error.message || 'Failed to load route component';
+        message.className = 'route-error-message';
+        const retryButton = document.createElement('button');
+        retryButton.textContent = 'Retry';
+        retryButton.className = 'route-error-retry';
+        retryButton.type = 'button';
+        retryButton.addEventListener('click', () => {
+            if (globalRouter) {
+                globalRouter.clearErrorCache();
+                update(); // Trigger retry
+            }
+        });
+        errorNode.appendChild(title);
+        errorNode.appendChild(message);
+        errorNode.appendChild(retryButton);
+        anchor.parentNode.insertBefore(errorNode, anchor.nextSibling);
+    };
+    const update = async () => {
+        if (!globalRouter || isUpdating)
+            return;
+        const route = globalRouter.currentRoute;
+        // Avoid unnecessary updates
+        if (route.path === currentPath && currentNode)
+            return;
+        isUpdating = true;
+        currentPath = route.path;
+        try {
+            const match = globalRouter['matcher'].match(route.path);
+            if (!match) {
+                cleanupNodes();
+                return;
+            }
+            const { route: routeDef } = match;
+            // Handle redirect routes (should be handled by router, but safety check)
+            if ('redirect' in routeDef) {
+                const redirectPath = typeof routeDef.redirect === 'function'
+                    ? routeDef.redirect(route)
+                    : routeDef.redirect;
+                queueMicrotask(() => globalRouter.navigate(redirectPath));
+                return;
+            }
+            // Handle component routes
+            if ('component' in routeDef) {
+                try {
+                    // Show loading for async components
+                    const isAsync = routeDef.component.constructor.name === 'AsyncFunction' ||
+                        routeDef.component.toString().includes('import(');
+                    if (isAsync) {
+                        showLoading();
+                    }
+                    const component = await globalRouter.loadComponent(routeDef, route.path);
+                    const node = component();
+                    if (node && anchor.parentNode && route.path === currentPath) {
+                        cleanupNodes();
+                        anchor.parentNode.insertBefore(node, anchor.nextSibling);
+                        currentNode = node;
+                    }
+                }
+                catch (error) {
+                    hideLoading();
+                    showError(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+        }
+        catch (error) {
+            console.error('[Route] Update failed:', error);
+            showError(error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            isUpdating = false;
+        }
+    };
+    // Set up reactive tracking
+    queueMicrotask(() => track(update, update));
+    return anchor;
+}
+// ============================================================================
+// ROUTER LINK COMPONENT
+// ============================================================================
+export function RouterLink(props) {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    const { to, replace = false, activeClass, exactActiveClass, children, target, rel, ...attrs } = props;
+    const route = globalRouter.currentRoute;
+    const href = globalRouter['resolvePath'](to);
+    // Calculate active states
+    const isActive = route.path.startsWith(href.split('?')[0].split('#')[0]);
+    const isExactActive = route.path === href.split('?')[0].split('#')[0];
+    const link = document.createElement('a');
+    link.href = href;
+    // Set target and rel for security
+    if (target) {
+        link.target = target;
+        // Security: Add rel="noopener noreferrer" for external links
+        if (target === '_blank') {
+            link.rel = rel ? `${rel} noopener noreferrer` : 'noopener noreferrer';
+        }
+        else if (rel) {
+            link.rel = rel;
+        }
+    }
+    else if (rel) {
+        link.rel = rel;
+    }
+    // Set active classes
+    const classes = [];
+    const options = globalRouter['options'];
+    if (isActive) {
+        if (activeClass)
+            classes.push(activeClass);
+        else if (options.linkActiveClass)
+            classes.push(options.linkActiveClass);
+    }
+    if (isExactActive) {
+        if (exactActiveClass)
+            classes.push(exactActiveClass);
+        else if (options.linkExactActiveClass)
+            classes.push(options.linkExactActiveClass);
+    }
+    if (classes.length > 0) {
+        link.className = classes.join(' ');
+    }
+    // Set other attributes (sanitize to prevent XSS)
+    Object.entries(attrs).forEach(([key, value]) => {
+        if (key.startsWith('on') || key === 'href')
+            return; // Skip event handlers and href
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            link.setAttribute(key, String(value));
+        }
+    });
+    // Set content
+    if (typeof children === 'string') {
+        link.textContent = children;
+    }
+    else if (children instanceof Node) {
+        link.appendChild(children);
+    }
+    else if (Array.isArray(children)) {
+        children.forEach(child => {
+            if (typeof child === 'string') {
+                link.appendChild(document.createTextNode(child));
+            }
+            else if (child instanceof Node) {
+                link.appendChild(child);
+            }
+        });
+    }
+    // Handle click for internal navigation
+    link.addEventListener('click', (e) => {
+        // Let browser handle external links, modified clicks, or when target is set
+        if (target ||
+            e.metaKey ||
+            e.ctrlKey ||
+            e.shiftKey ||
+            e.altKey ||
+            e.button !== 0) {
+            return;
+        }
+        e.preventDefault();
+        globalRouter.navigate(to, { replace });
+    });
+    return link;
+}
+// ============================================================================
+// SUSPENSE COMPONENT (for code splitting)
+// ============================================================================
+export function Suspense(props) {
+    const anchor = document.createComment("suspense-boundary");
+    let currentNode = null;
+    let fallbackNode = null;
+    let isLoading = false;
+    const cleanupNodes = () => {
+        [currentNode, fallbackNode].forEach(node => {
+            if (node?.parentNode) {
+                node.parentNode.removeChild(node);
+            }
+        });
+        currentNode = null;
+        fallbackNode = null;
+    };
+    const showFallback = () => {
+        if (fallbackNode || !props.fallback || !anchor.parentNode)
+            return;
+        try {
+            const fallback = typeof props.fallback === 'function'
+                ? props.fallback()
+                : props.fallback;
+            if (fallback instanceof HTMLElement) {
+                fallbackNode = fallback;
+                anchor.parentNode.insertBefore(fallbackNode, anchor.nextSibling);
+            }
+        }
+        catch (error) {
+            console.error('[Suspense] Fallback error:', error);
+        }
+    };
+    const hideFallback = () => {
+        if (fallbackNode?.parentNode) {
+            fallbackNode.parentNode.removeChild(fallbackNode);
+            fallbackNode = null;
+        }
+    };
+    const render = async () => {
+        if (isLoading)
+            return;
+        isLoading = true;
+        try {
+            const result = props.children();
+            if (result instanceof Promise) {
+                showFallback();
+                const element = await result;
+                if (anchor.parentNode) {
+                    cleanupNodes();
+                    anchor.parentNode.insertBefore(element, anchor.nextSibling);
+                    currentNode = element;
+                }
+            }
+            else {
+                if (anchor.parentNode) {
+                    cleanupNodes();
+                    anchor.parentNode.insertBefore(result, anchor.nextSibling);
+                    currentNode = result;
+                }
+            }
+        }
+        catch (error) {
+            hideFallback();
+            console.error('[Suspense] Children error:', error);
+            // Show error in place of content
+            if (anchor.parentNode) {
+                const errorElement = document.createElement('div');
+                errorElement.className = 'suspense-error';
+                errorElement.textContent = error instanceof Error ? error.message : 'Failed to load';
+                cleanupNodes();
+                anchor.parentNode.insertBefore(errorElement, anchor.nextSibling);
+                currentNode = errorElement;
+            }
+        }
+        finally {
+            isLoading = false;
+        }
+    };
+    queueMicrotask(render);
+    return anchor;
+}
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+/**
+ * Creates a lazy-loaded component
+ */
+export function lazy(importFn) {
+    return importFn;
+}
+/**
+ * Preloads a route component
+ */
+export async function preloadRoute(to) {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    const path = globalRouter['resolvePath'](to);
+    const match = globalRouter['matcher'].match(path.split('?')[0].split('#')[0]);
+    if (match && 'component' in match.route) {
+        try {
+            await globalRouter.loadComponent(match.route, path);
+        }
+        catch (error) {
+            console.warn('[Router] Preload failed:', error);
+        }
+    }
+}
+/**
+ * Validates if a route exists
+ */
+export function hasRoute(name) {
+    if (!globalRouter)
+        return false;
+    return globalRouter['matcher'].findByName(name) !== null;
+}
+/**
+ * Gets route information by name
+ */
+export function getRouteInfo(name) {
+    if (!globalRouter)
+        return null;
+    return globalRouter['matcher'].findByName(name);
+}
+/**
+ * Builds a URL for a route
+ */
+export function buildURL(to) {
+    if (!globalRouter)
+        throw new Error('Router not initialized. Call createRouter() first.');
+    return globalRouter['resolvePath'](to);
+}
+// ============================================================================
+// CLEANUP
+// ============================================================================
+export function destroyRouter() {
+    if (globalRouter) {
+        globalRouter.destroy();
+        globalRouter = null;
+    }
+}
+// Cleanup on page unload
+if (typeof window !== 'undefined') {
+    window.addEventListener('beforeunload', () => {
+        destroyRouter();
+    });
+}