@astermind/cybernetic-chatbot-client 2.2.14 → 2.2.21

package/dist/cybernetic-chatbot-client.esm.js

@@ -1,3 +1,4 @@
+import { useState, useRef, useCallback, useEffect } from 'react';
 import 'fs';
 import 'path';
 
@@ -2660,6 +2661,555 @@ const configLoaders = {
     loadFromScriptAttributes
 };
 
+// src/agentic/SiteMapDiscovery.ts
+// Multi-source sitemap discovery and merging for agentic navigation
+/**
+ * Multi-source sitemap discovery and management
+ *
+ * Combines routes from three sources:
+ * 1. Static props (explicit configuration)
+ * 2. Framework auto-discovery (React Router, Vue Router, etc.)
+ * 3. Backend API (tenant-specific sitemaps)
+ */
+class SiteMapDiscovery {
+    constructor(config, apiUrl, apiKey) {
+        this.staticEntries = [];
+        this.discoveredEntries = [];
+        this.backendEntries = [];
+        this.backendCache = null;
+        this.isInitialized = false;
+        this.initPromise = null;
+        this.config = config;
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+        // Load static entries immediately (synchronous)
+        if (config.static) {
+            this.staticEntries = this.enhanceEntries(config.static, 'props');
+        }
+    }
+    /**
+     * Initialize all sitemap sources
+     * Call this during widget initialization or first query based on loadStrategy
+     */
+    async initialize() {
+        if (this.isInitialized)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = this.performInitialization();
+        await this.initPromise;
+        this.isInitialized = true;
+    }
+    async performInitialization() {
+        const tasks = [];
+        // Source 2: Framework auto-discovery
+        if (this.config.discovery?.enabled !== false) {
+            tasks.push(this.discoverFromFramework());
+        }
+        // Source 3: Backend API
+        if (this.config.backend?.enabled !== false && this.config.backend?.endpoint) {
+            tasks.push(this.fetchFromBackend());
+        }
+        const results = await Promise.allSettled(tasks);
+        for (const result of results) {
+            if (result.status === 'fulfilled') {
+                const { entries, source } = result.value;
+                if (source === 'discovery') {
+                    this.discoveredEntries = entries;
+                }
+                else if (source === 'backend') {
+                    this.backendEntries = entries;
+                }
+            }
+            else {
+                console.warn('[SiteMapDiscovery] Source failed:', result.reason);
+            }
+        }
+        const total = this.staticEntries.length + this.discoveredEntries.length + this.backendEntries.length;
+        console.log(`[SiteMapDiscovery] Initialized with ${total} total entries (${this.staticEntries.length} static, ${this.discoveredEntries.length} discovered, ${this.backendEntries.length} backend)`);
+    }
+    /**
+     * Get merged sitemap entries with deduplication
+     */
+    getMergedEntries() {
+        return this.mergeEntries(this.staticEntries, this.discoveredEntries, this.backendEntries);
+    }
+    /**
+     * Convert to legacy AgenticSiteMapEntry format for classifier compatibility
+     */
+    getLegacyEntries() {
+        return this.getMergedEntries().map(e => ({
+            path: e.path,
+            name: e.name,
+            description: e.description,
+            params: e.params,
+            dynamicParams: e.dynamicParams,
+            aliases: e.aliases
+        }));
+    }
+    // ==================== SOURCE 2: FRAMEWORK DISCOVERY ====================
+    async discoverFromFramework() {
+        const config = this.config.discovery || {};
+        const entries = [];
+        try {
+            // Detect framework if not specified
+            const framework = config.framework || this.detectFramework();
+            let routes = [];
+            switch (framework) {
+                case 'react-router':
+                    routes = this.discoverReactRouter();
+                    break;
+                case 'vue-router':
+                    routes = this.discoverVueRouter();
+                    break;
+                case 'next':
+                    routes = this.discoverNextRoutes();
+                    break;
+                case 'angular':
+                    routes = this.discoverAngularRoutes();
+                    break;
+                default:
+                    if (config.domFallback !== false) {
+                        routes = this.discoverFromDOM(config.navSelectors);
+                    }
+            }
+            // Transform routes to sitemap entries
+            for (const route of routes) {
+                // Apply exclude patterns
+                if (this.shouldExcludeRoute(route.path, config.excludePaths)) {
+                    continue;
+                }
+                // Apply custom transform if provided
+                let entry;
+                if (config.transformRoute) {
+                    entry = config.transformRoute(route);
+                }
+                else {
+                    entry = this.defaultRouteTransform(route);
+                }
+                if (entry) {
+                    entries.push(this.enhanceEntry(entry, 'discovery'));
+                }
+            }
+            console.log(`[SiteMapDiscovery] Discovered ${entries.length} routes from ${framework}`);
+        }
+        catch (error) {
+            console.warn('[SiteMapDiscovery] Framework discovery failed:', error);
+            return {
+                entries: [],
+                source: 'discovery',
+                timestamp: Date.now(),
+                error: String(error)
+            };
+        }
+        return {
+            entries,
+            source: 'discovery',
+            timestamp: Date.now()
+        };
+    }
+    /**
+     * Detect JavaScript framework from global objects
+     */
+    detectFramework() {
+        if (typeof window === 'undefined')
+            return 'generic';
+        const win = window;
+        // React Router v6.4+ data router
+        if (win.__REACT_ROUTER_DATA_ROUTER__) {
+            return 'react-router';
+        }
+        // React Router v5 context
+        if (win.__reactRouterContext) {
+            return 'react-router';
+        }
+        // Vue Router
+        if (win.__VUE_ROUTER__ || win.__VUE_APP__?.$router) {
+            return 'vue-router';
+        }
+        // Next.js
+        if (win.__NEXT_DATA__) {
+            return 'next';
+        }
+        // Angular
+        if (win.ng || document.querySelector('[ng-version]')) {
+            return 'angular';
+        }
+        return 'generic';
+    }
+    /**
+     * Discover routes from React Router
+     */
+    discoverReactRouter() {
+        const routes = [];
+        if (typeof window === 'undefined')
+            return routes;
+        const win = window;
+        // Try React Router v6.4+ data router
+        const dataRouter = win.__REACT_ROUTER_DATA_ROUTER__;
+        if (dataRouter?.routes) {
+            this.extractRoutesFromConfig(dataRouter.routes, routes, '');
+            return routes;
+        }
+        // Fallback: Try to find routes from __REACT_DEVTOOLS_GLOBAL_HOOK__
+        // This is less reliable but can work in some cases
+        return routes;
+    }
+    /**
+     * Extract routes recursively from React Router config
+     */
+    extractRoutesFromConfig(routeConfigs, routes, parentPath) {
+        for (const config of routeConfigs) {
+            const path = this.normalizePath(parentPath, config.path || '');
+            // Extract route info from handle metadata
+            const route = {
+                path,
+                name: config.handle?.name || config.handle?.title || config.id,
+                meta: config.handle || {},
+                children: []
+            };
+            // Only include routes with paths (skip layout routes without path)
+            if (config.path || config.index) {
+                routes.push(route);
+            }
+            // Recursively process children
+            if (config.children) {
+                this.extractRoutesFromConfig(config.children, routes, path);
+            }
+        }
+    }
+    /**
+     * Discover routes from Vue Router
+     */
+    discoverVueRouter() {
+        const routes = [];
+        if (typeof window === 'undefined')
+            return routes;
+        const win = window;
+        // Access Vue Router instance
+        const app = win.__VUE_APP__;
+        const router = app?.$router || win.__VUE_ROUTER__;
+        if (router?.getRoutes) {
+            const vueRoutes = router.getRoutes();
+            for (const vueRoute of vueRoutes) {
+                routes.push({
+                    path: vueRoute.path,
+                    name: vueRoute.name?.toString(),
+                    meta: vueRoute.meta || {},
+                    component: vueRoute.components?.default?.name
+                });
+            }
+        }
+        return routes;
+    }
+    /**
+     * Discover routes from Next.js
+     */
+    discoverNextRoutes() {
+        const routes = [];
+        if (typeof window === 'undefined')
+            return routes;
+        const win = window;
+        const nextData = win.__NEXT_DATA__;
+        if (!nextData)
+            return routes;
+        // Next.js doesn't expose routes directly in client
+        // We can extract from build manifest if available
+        const pages = nextData.buildManifest?.pages || {};
+        for (const pagePath of Object.keys(pages)) {
+            if (pagePath.startsWith('/_'))
+                continue; // Skip internal pages
+            routes.push({
+                path: pagePath,
+                name: this.pathToName(pagePath)
+            });
+        }
+        return routes;
+    }
+    /**
+     * Discover routes from Angular Router
+     */
+    discoverAngularRoutes() {
+        // Angular route discovery requires access to Router service
+        // which is typically not exposed globally
+        // Users should provide routes via props or backend
+        return [];
+    }
+    /**
+     * Discover routes by scanning DOM navigation elements
+     */
+    discoverFromDOM(selectors) {
+        const routes = [];
+        if (typeof document === 'undefined')
+            return routes;
+        const defaultSelectors = [
+            'nav a[href]',
+            '[role="navigation"] a[href]',
+            '.nav a[href]',
+            '.navigation a[href]',
+            '.sidebar a[href]',
+            '.menu a[href]',
+            'header a[href]'
+        ];
+        const allSelectors = selectors || defaultSelectors;
+        const seen = new Set();
+        for (const selector of allSelectors) {
+            try {
+                const links = document.querySelectorAll(selector);
+                for (const link of links) {
+                    const href = link.getAttribute('href');
+                    if (!href)
+                        continue;
+                    // Only process internal links
+                    if (href.startsWith('http') && !href.startsWith(window.location.origin)) {
+                        continue;
+                    }
+                    // Normalize path
+                    const path = href.startsWith('/') ? href : `/${href}`;
+                    // Skip duplicates, anchors, and special links
+                    if (seen.has(path) || path.startsWith('/#') || path === '/' || path.includes('javascript:')) {
+                        continue;
+                    }
+                    seen.add(path);
+                    // Clean path (remove query string and hash)
+                    const cleanPath = path.split('?')[0].split('#')[0];
+                    routes.push({
+                        path: cleanPath,
+                        name: link.textContent?.trim() || this.pathToName(cleanPath)
+                    });
+                }
+            }
+            catch (e) {
+                // Invalid selector - skip
+            }
+        }
+        return routes;
+    }
+    // ==================== SOURCE 3: BACKEND API ====================
+    async fetchFromBackend() {
+        const config = this.config.backend || {};
+        const endpoint = config.endpoint || '/api/external/sitemap';
+        // Check cache
+        if (this.backendCache && Date.now() < this.backendCache.expiresAt) {
+            return {
+                entries: this.backendCache.entries,
+                source: 'backend',
+                timestamp: this.backendCache.fetchedAt
+            };
+        }
+        try {
+            const url = new URL(endpoint, this.apiUrl);
+            // Add query params
+            if (config.tenantScoped !== false) {
+                url.searchParams.set('tenantScoped', 'true');
+            }
+            if (config.includeGeneral !== false) {
+                url.searchParams.set('includeGeneral', 'true');
+            }
+            const response = await fetch(url.toString(), {
+                method: 'GET',
+                headers: {
+                    'X-API-Key': this.apiKey,
+                    'Content-Type': 'application/json',
+                    ...config.headers
+                }
+            });
+            if (!response.ok) {
+                throw new Error(`Backend sitemap fetch failed: ${response.status}`);
+            }
+            const data = await response.json();
+            const entries = this.transformBackendResponse(data);
+            // Update cache
+            const ttl = config.cacheTtl || 300000; // 5 minutes default
+            this.backendCache = {
+                entries,
+                fetchedAt: Date.now(),
+                expiresAt: Date.now() + ttl
+            };
+            console.log(`[SiteMapDiscovery] Loaded ${entries.length} routes from backend`);
+            return {
+                entries,
+                source: 'backend',
+                timestamp: Date.now()
+            };
+        }
+        catch (error) {
+            console.warn('[SiteMapDiscovery] Backend fetch failed:', error);
+            return {
+                entries: this.backendCache?.entries || [],
+                source: 'backend',
+                timestamp: Date.now(),
+                error: String(error)
+            };
+        }
+    }
+    /**
+     * Transform backend response to enhanced entries
+     */
+    transformBackendResponse(data) {
+        // Handle array or object with entries/sitemap key
+        const rawEntries = Array.isArray(data)
+            ? data
+            : data.entries || data.sitemap || data.routes || [];
+        return rawEntries.map((entry) => this.enhanceEntry({
+            path: entry.url || entry.path,
+            name: entry.title || entry.name,
+            description: entry.description,
+            aliases: entry.keywords || entry.aliases,
+            params: entry.params,
+            dynamicParams: entry.dynamicParams
+        }, 'backend'));
+    }
+    // ==================== MERGE LOGIC ====================
+    /**
+     * Merge entries from all sources with deduplication
+     */
+    mergeEntries(...sources) {
+        const mergeConfig = this.config.merge || {};
+        const priorityOrder = mergeConfig.sourcePriority || ['props', 'backend', 'discovery'];
+        const dedupeStrategy = mergeConfig.deduplication || 'path';
+        // Create priority map (higher number = higher priority)
+        const priorityMap = new Map();
+        priorityOrder.forEach((source, index) => {
+            priorityMap.set(source, priorityOrder.length - index);
+        });
+        // Flatten all entries with priority scores
+        const allEntries = [];
+        for (const sourceEntries of sources) {
+            for (const entry of sourceEntries) {
+                const priority = priorityMap.get(entry._source || 'props') || 0;
+                allEntries.push({ ...entry, _priority: priority });
+            }
+        }
+        // Sort by priority (higher first)
+        allEntries.sort((a, b) => (b._priority || 0) - (a._priority || 0));
+        // Deduplicate
+        const seen = new Map();
+        for (const entry of allEntries) {
+            let key;
+            switch (dedupeStrategy) {
+                case 'name':
+                    key = entry.name.toLowerCase();
+                    break;
+                case 'both':
+                    key = `${entry.path}|${entry.name.toLowerCase()}`;
+                    break;
+                case 'path':
+                default:
+                    key = this.normalizePath('', entry.path);
+            }
+            if (!seen.has(key)) {
+                seen.set(key, entry);
+            }
+            else if (mergeConfig.keepNonConflicting !== false) {
+                // Merge non-conflicting fields from lower priority entry
+                const existing = seen.get(key);
+                if (!existing.description && entry.description) {
+                    existing.description = entry.description;
+                }
+                if (!existing.aliases?.length && entry.aliases?.length) {
+                    existing.aliases = entry.aliases;
+                }
+            }
+        }
+        return Array.from(seen.values());
+    }
+    // ==================== HELPERS ====================
+    enhanceEntries(entries, source) {
+        return entries.map(e => this.enhanceEntry(e, source));
+    }
+    enhanceEntry(entry, source) {
+        return {
+            ...entry,
+            _source: source,
+            _discoveredAt: Date.now()
+        };
+    }
+    /**
+     * Default transformation from DiscoveredRoute to AgenticSiteMapEntry
+     */
+    defaultRouteTransform(route) {
+        // Skip routes without meaningful paths
+        if (!route.path || route.path === '*' || route.path === '**') {
+            return null;
+        }
+        return {
+            path: route.path,
+            name: route.name || route.meta?.title || this.pathToName(route.path),
+            description: route.meta?.description,
+            aliases: route.meta?.keywords || route.meta?.aliases,
+            dynamicParams: route.path.includes(':') || route.path.includes('[')
+        };
+    }
+    /**
+     * Normalize path by combining parent and child paths
+     */
+    normalizePath(parent, path) {
+        if (!path || path === '/')
+            return parent || '/';
+        if (path.startsWith('/'))
+            return path;
+        if (!parent || parent === '/')
+            return `/${path}`;
+        return `${parent}/${path}`.replace(/\/+/g, '/');
+    }
+    /**
+     * Convert path to human-readable name
+     */
+    pathToName(path) {
+        const segments = path.split('/').filter(Boolean);
+        const last = segments[segments.length - 1] || 'Home';
+        return last
+            .replace(/[-_]/g, ' ')
+            .replace(/\[.*?\]/g, '') // Remove Next.js dynamic segments
+            .replace(/:/g, '') // Remove React Router params
+            .split(' ')
+            .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+            .join(' ')
+            .trim() || 'Page';
+    }
+    /**
+     * Check if route should be excluded based on glob patterns
+     */
+    shouldExcludeRoute(path, patterns) {
+        if (!patterns?.length)
+            return false;
+        for (const pattern of patterns) {
+            // Simple glob matching (supports * wildcard)
+            const regex = new RegExp('^' + pattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+            if (regex.test(path))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Force refresh from all sources
+     */
+    async refresh() {
+        this.backendCache = null;
+        this.isInitialized = false;
+        this.initPromise = null;
+        await this.initialize();
+    }
+    /**
+     * Check if initialized
+     */
+    isReady() {
+        return this.isInitialized;
+    }
+    /**
+     * Get current entry counts by source
+     */
+    getStats() {
+        return {
+            static: this.staticEntries.length,
+            discovered: this.discoveredEntries.length,
+            backend: this.backendEntries.length,
+            merged: this.getMergedEntries().length
+        };
+    }
+}
+
 // src/agentic/CyberneticIntentClassifier.ts
 // Hybrid intent classification for agentic capabilities
 /**
@@ -2702,15 +3252,28 @@ const ACTION_PATTERNS = {
  * a local DOM action or be sent to the backend RAG.
  */
 class CyberneticIntentClassifier {
-    constructor(config) {
+    /**
+     * Create a new intent classifier
+     *
+     * @param config - Agent configuration
+     * @param apiUrl - Backend API URL (for multi-source sitemap)
+     * @param apiKey - API key for authentication
+     */
+    constructor(config, apiUrl = '', apiKey = '') {
         this.categories = [];
         this.topicKeywords = new Map(); // topic -> keywords
+        /** Multi-source sitemap discovery instance */
+        this.siteMapDiscovery = null;
         this.config = config;
         this.siteMapIndex = new Map();
         this.formIndex = new Map();
         this.modalIndex = new Map();
         // Build indexes for fast lookup
         this.buildIndexes();
+        // Initialize multi-source sitemap discovery if configured
+        if (config.siteMapConfig) {
+            this.siteMapDiscovery = new SiteMapDiscovery(config.siteMapConfig, apiUrl, apiKey);
+        }
     }
     /**
      * Build search indexes from configuration
@@ -2981,22 +3544,35 @@ class CyberneticIntentClassifier {
         }
         return '';
     }
+    /**
+     * Strip common articles and filler words for better matching
+     */
+    stripArticles(text) {
+        return text
+            .replace(/^(the|a|an|my|our|your|this|that)\s+/gi, '')
+            .replace(/\s+(page|section|screen|view)$/gi, '')
+            .trim();
+    }
     /**
      * Find site map match for target string
      */
     findSiteMapMatch(target) {
         const normalizedTarget = target.toLowerCase().replace(/[^a-z0-9\s]/g, '');
-        // Exact match
-        const exact = this.siteMapIndex.get(normalizedTarget);
+        const strippedTarget = this.stripArticles(normalizedTarget);
+        // Exact match (try both with and without articles)
+        const exact = this.siteMapIndex.get(normalizedTarget) || this.siteMapIndex.get(strippedTarget);
         if (exact) {
             return { entry: exact, similarity: 1.0 };
         }
-        // Fuzzy match
+        // Fuzzy match using stripped version for better accuracy
         let bestMatch = null;
         let bestScore = 0;
         for (const [key, entry] of this.siteMapIndex) {
-            const score = this.calculateSimilarity(normalizedTarget, key);
-            if (score > bestScore && score > 0.6) {
+            // Compare both original and stripped versions, take the better score
+            const score1 = this.calculateSimilarity(normalizedTarget, key);
+            const score2 = this.calculateSimilarity(strippedTarget, key);
+            const score = Math.max(score1, score2);
+            if (score > bestScore && score > 0.5) {
                 bestScore = score;
                 bestMatch = entry;
             }
@@ -3393,6 +3969,124 @@ class CyberneticIntentClassifier {
     isTrained() {
         return this.categories.length > 0 || this.topicKeywords.size > 0;
     }
+    // ==================== MULTI-SOURCE SITEMAP DISCOVERY ====================
+    /**
+     * Initialize multi-source sitemap discovery
+     * Call this after construction to load all sitemap sources
+     *
+     * @returns Promise that resolves when discovery is complete
+     */
+    async initializeDiscovery() {
+        if (!this.siteMapDiscovery) {
+            console.log('[CyberneticIntentClassifier] No siteMapConfig provided, skipping discovery');
+            return;
+        }
+        try {
+            await this.siteMapDiscovery.initialize();
+            this.rebuildIndexesFromDiscovery();
+            console.log(`[CyberneticIntentClassifier] Discovery complete, indexed ${this.siteMapIndex.size} entries`);
+        }
+        catch (error) {
+            console.error('[CyberneticIntentClassifier] Discovery initialization failed:', error);
+        }
+    }
+    /**
+     * Rebuild sitemap indexes from discovery results
+     * Merges discovered entries with existing static config
+     */
+    rebuildIndexesFromDiscovery() {
+        if (!this.siteMapDiscovery)
+            return;
+        // Get merged entries from discovery (includes static props)
+        const mergedEntries = this.siteMapDiscovery.getLegacyEntries();
+        // Clear existing sitemap index (keep form and modal indexes)
+        this.siteMapIndex.clear();
+        // Index all merged entries
+        for (const entry of mergedEntries) {
+            const siteMapEntry = {
+                path: entry.path,
+                name: entry.name,
+                description: entry.description,
+                params: entry.params,
+                aliases: entry.aliases
+            };
+            // Index by name and aliases
+            const keys = [
+                entry.name.toLowerCase(),
+                entry.path.toLowerCase(),
+                ...(entry.aliases || []).map(a => a.toLowerCase())
+            ];
+            // Also index description words for fuzzy matching
+            if (entry.description) {
+                const descWords = entry.description
+                    .toLowerCase()
+                    .split(/\s+/)
+                    .filter(w => w.length > 4 && !this.isStopWord(w));
+                keys.push(...descWords);
+            }
+            for (const key of keys) {
+                this.siteMapIndex.set(key, siteMapEntry);
+            }
+        }
+    }
+    /**
+     * Check if sitemap discovery is ready
+     *
+     * @returns true if discovery is complete and entries are loaded
+     */
+    isSiteMapReady() {
+        if (!this.siteMapDiscovery) {
+            // No discovery configured - check if static sitemap exists
+            return this.siteMapIndex.size > 0 || (this.config.siteMap?.length ?? 0) > 0;
+        }
+        return this.siteMapDiscovery.isReady();
+    }
+    /**
+     * Ensure sitemap is ready before classification
+     * Initializes discovery if not already done
+     *
+     * @returns Promise that resolves when sitemap is ready
+     */
+    async ensureSiteMapReady() {
+        if (this.isSiteMapReady()) {
+            return;
+        }
+        await this.initializeDiscovery();
+    }
+    /**
+     * Refresh sitemap from all sources
+     * Forces reload of backend and re-discovery
+     *
+     * @returns Promise that resolves when refresh is complete
+     */
+    async refreshSiteMap() {
+        if (!this.siteMapDiscovery) {
+            console.log('[CyberneticIntentClassifier] No siteMapConfig provided, cannot refresh');
+            return;
+        }
+        await this.siteMapDiscovery.refresh();
+        this.rebuildIndexesFromDiscovery();
+    }
+    /**
+     * Get the SiteMapDiscovery instance for advanced use cases
+     *
+     * @returns The SiteMapDiscovery instance or null if not configured
+     */
+    getSiteMapDiscovery() {
+        return this.siteMapDiscovery;
+    }
+    /**
+     * Get current sitemap entries (merged from all sources)
+     *
+     * @returns Array of sitemap entries
+     */
+    getSiteMapEntries() {
+        if (this.siteMapDiscovery) {
+            return this.siteMapDiscovery.getLegacyEntries();
+        }
+        // Fall back to static config
+        return this.config.siteMap || [];
+    }
 }
 
 // src/agentic/CyberneticAgent.ts
@@ -4029,6 +4723,284 @@ function registerAgenticCapabilities(client) {
     client.registerAgentic(capabilities);
 }
 
+// src/hooks/useSiteMapDiscovery.ts
+// React hook for sitemap discovery integration
+// Note: React is a peer dependency - this hook is optional for non-React consumers
+/**
+ * Hook for discovering routes from React Router and other frameworks
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { entries, isDiscovering } = useSiteMapDiscovery({
+ *     enabled: true,
+ *     excludePaths: ['/admin/*', '/internal/*']
+ *   });
+ *
+ *   return (
+ *     <ChatbotWidget
+ *       agent={{
+ *         enabled: true,
+ *         siteMap: entries
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+function useSiteMapDiscovery(options = {}) {
+    const { enabled = true, transformRoute: _transformRoute, excludePaths: _excludePaths = [], navSelectors: _navSelectors, disableDomFallback = false } = options;
+    const [state, setState] = useState({
+        entries: [],
+        isDiscovering: false,
+        error: null,
+        framework: null
+    });
+    const discoveredRef = useRef(false);
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    /**
+     * Detect JavaScript framework
+     */
+    const detectFramework = useCallback(() => {
+        if (typeof window === 'undefined')
+            return 'generic';
+        const win = window;
+        if (win.__REACT_ROUTER_DATA_ROUTER__)
+            return 'react-router';
+        if (win.__reactRouterContext)
+            return 'react-router';
+        if (win.__VUE_ROUTER__ || win.__VUE_APP__?.$router)
+            return 'vue-router';
+        if (win.__NEXT_DATA__)
+            return 'next';
+        if (win.ng || document.querySelector('[ng-version]'))
+            return 'angular';
+        return 'generic';
+    }, []);
+    /**
+     * Check if path should be excluded
+     */
+    const shouldExclude = useCallback((path) => {
+        const patterns = optionsRef.current.excludePaths || [];
+        for (const pattern of patterns) {
+            const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+            if (regex.test(path))
+                return true;
+        }
+        return false;
+    }, []);
+    /**
+     * Convert path to human-readable name
+     */
+    const pathToName = useCallback((path) => {
+        const segments = path.split('/').filter(Boolean);
+        const last = segments[segments.length - 1] || 'Home';
+        return last
+            .replace(/[-_:]/g, ' ')
+            .replace(/\[.*?\]/g, '')
+            .split(' ')
+            .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+            .join(' ')
+            .trim() || 'Page';
+    }, []);
+    /**
+     * Default route transform
+     */
+    const defaultTransform = useCallback((route) => {
+        if (!route.path || route.path === '*' || route.path === '**')
+            return null;
+        return {
+            path: route.path,
+            name: route.name || route.meta?.title || pathToName(route.path),
+            description: route.meta?.description,
+            aliases: route.meta?.keywords || route.meta?.aliases,
+            dynamicParams: route.path.includes(':') || route.path.includes('[')
+        };
+    }, [pathToName]);
+    /**
+     * Extract routes from React Router config
+     */
+    const extractReactRouterRoutes = useCallback((routeConfigs, routes, parentPath) => {
+        for (const config of routeConfigs) {
+            let path = config.path || '';
+            if (path && !path.startsWith('/')) {
+                path = parentPath ? `${parentPath}/${path}`.replace(/\/+/g, '/') : `/${path}`;
+            }
+            else if (!path && parentPath) {
+                path = parentPath;
+            }
+            const route = {
+                path,
+                name: config.handle?.name || config.handle?.title || config.id,
+                meta: config.handle || {}
+            };
+            if (config.path && !shouldExclude(path)) {
+                routes.push(route);
+            }
+            if (config.children) {
+                extractReactRouterRoutes(config.children, routes, path);
+            }
+        }
+    }, [shouldExclude]);
+    /**
+     * Discover routes from DOM navigation
+     */
+    const discoverFromDOM = useCallback(() => {
+        if (typeof document === 'undefined')
+            return [];
+        const defaultSelectors = [
+            'nav a[href]',
+            '[role="navigation"] a[href]',
+            '.nav a[href]',
+            '.sidebar a[href]',
+            '.menu a[href]',
+            'header a[href]'
+        ];
+        const selectors = optionsRef.current.navSelectors || defaultSelectors;
+        const routes = [];
+        const seen = new Set();
+        for (const selector of selectors) {
+            try {
+                const links = document.querySelectorAll(selector);
+                for (const link of links) {
+                    const href = link.getAttribute('href');
+                    if (!href || href.startsWith('http') || href.startsWith('javascript:'))
+                        continue;
+                    const path = href.startsWith('/') ? href : `/${href}`;
+                    const cleanPath = path.split('?')[0].split('#')[0];
+                    if (seen.has(cleanPath) || cleanPath === '/' || shouldExclude(cleanPath))
+                        continue;
+                    seen.add(cleanPath);
+                    routes.push({
+                        path: cleanPath,
+                        name: link.textContent?.trim() || pathToName(cleanPath)
+                    });
+                }
+            }
+            catch (e) {
+                // Invalid selector
+            }
+        }
+        return routes;
+    }, [shouldExclude, pathToName]);
+    /**
+     * Main discovery function
+     */
+    const discoverRoutes = useCallback(() => {
+        if (!enabled || typeof window === 'undefined') {
+            return;
+        }
+        setState((prev) => ({ ...prev, isDiscovering: true, error: null }));
+        try {
+            const framework = detectFramework();
+            const routes = [];
+            const win = window;
+            // Try framework-specific discovery
+            if (framework === 'react-router' && win.__REACT_ROUTER_DATA_ROUTER__?.routes) {
+                extractReactRouterRoutes(win.__REACT_ROUTER_DATA_ROUTER__.routes, routes, '');
+            }
+            else if (framework === 'vue-router') {
+                const router = win.__VUE_APP__?.$router || win.__VUE_ROUTER__;
+                if (router?.getRoutes) {
+                    for (const vueRoute of router.getRoutes()) {
+                        if (!shouldExclude(vueRoute.path)) {
+                            routes.push({
+                                path: vueRoute.path,
+                                name: vueRoute.name?.toString(),
+                                meta: vueRoute.meta || {}
+                            });
+                        }
+                    }
+                }
+            }
+            else if (framework === 'next' && win.__NEXT_DATA__?.buildManifest?.pages) {
+                for (const pagePath of Object.keys(win.__NEXT_DATA__.buildManifest.pages)) {
+                    if (!pagePath.startsWith('/_') && !shouldExclude(pagePath)) {
+                        routes.push({
+                            path: pagePath,
+                            name: pathToName(pagePath)
+                        });
+                    }
+                }
+            }
+            // DOM fallback if no routes found and not disabled
+            if (routes.length === 0 && !disableDomFallback) {
+                routes.push(...discoverFromDOM());
+            }
+            // Transform routes to sitemap entries
+            const transform = optionsRef.current.transformRoute || defaultTransform;
+            const entries = [];
+            for (const route of routes) {
+                const entry = transform(route);
+                if (entry) {
+                    entries.push(entry);
+                }
+            }
+            setState({
+                entries,
+                isDiscovering: false,
+                error: null,
+                framework
+            });
+            discoveredRef.current = true;
+            console.log(`[useSiteMapDiscovery] Discovered ${entries.length} routes from ${framework}`);
+        }
+        catch (error) {
+            console.warn('[useSiteMapDiscovery] Discovery failed:', error);
+            setState((prev) => ({
+                ...prev,
+                isDiscovering: false,
+                error: String(error)
+            }));
+        }
+    }, [
+        enabled,
+        detectFramework,
+        extractReactRouterRoutes,
+        discoverFromDOM,
+        defaultTransform,
+        shouldExclude,
+        pathToName,
+        disableDomFallback
+    ]);
+    // Initial discovery with delay to ensure router is mounted
+    useEffect(() => {
+        if (!enabled || discoveredRef.current)
+            return;
+        const timer = setTimeout(discoverRoutes, 100);
+        return () => clearTimeout(timer);
+    }, [enabled, discoverRoutes]);
+    // Re-discover on location changes (for SPAs)
+    useEffect(() => {
+        if (!enabled || typeof window === 'undefined')
+            return;
+        const handlePopState = () => {
+            // Re-run discovery after navigation (routes might have changed)
+            setTimeout(discoverRoutes, 50);
+        };
+        window.addEventListener('popstate', handlePopState);
+        return () => window.removeEventListener('popstate', handlePopState);
+    }, [enabled, discoverRoutes]);
+    return {
+        ...state,
+        refresh: discoverRoutes
+    };
+}
+/**
+ * Create a FrameworkDiscoveryConfig from hook options
+ * Useful for passing to CyberneticClient
+ */
+function createDiscoveryConfig(options) {
+    return {
+        enabled: options.enabled ?? true,
+        domFallback: !options.disableDomFallback,
+        navSelectors: options.navSelectors,
+        excludePaths: options.excludePaths,
+        transformRoute: options.transformRoute
+    };
+}
+
 // © 2026 AsterMind AI Co. – All Rights Reserved.
 // Patent Pending US 63/897,713
 // ELMConfig.ts - Configuration interfaces, defaults, helpers for ELM-based models
@@ -5424,5 +6396,5 @@ function createClient(config) {
     return new CyberneticClient(config);
 }
 
-export { ApiClient, CyberneticAgent, CyberneticCache, CyberneticClient, CyberneticIntentClassifier, CyberneticLocalRAG, CyberneticOfflineStorage, LicenseManager, OmegaOfflineRAG, REQUIRED_FEATURES, configLoaders, createClient, createLicenseManager, detectEnvironment, getEnforcementMode, getTokenExpiration, isValidJWTFormat, loadConfig, registerAgenticCapabilities, validateConfig, verifyLicenseToken };
+export { ApiClient, CyberneticAgent, CyberneticCache, CyberneticClient, CyberneticIntentClassifier, CyberneticLocalRAG, CyberneticOfflineStorage, LicenseManager, OmegaOfflineRAG, REQUIRED_FEATURES, SiteMapDiscovery, configLoaders, createClient, createDiscoveryConfig, createLicenseManager, detectEnvironment, getEnforcementMode, getTokenExpiration, isValidJWTFormat, loadConfig, registerAgenticCapabilities, useSiteMapDiscovery, validateConfig, verifyLicenseToken };
 //# sourceMappingURL=cybernetic-chatbot-client.esm.js.map