@astermind/cybernetic-chatbot-client 2.2.14 → 2.2.21

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

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('fs'), require('path')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'fs', 'path'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.AsterMindCybernetic = {}));
-})(this, (function (exports) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('react'), require('fs'), require('path')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'react', 'fs', 'path'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.AsterMindCybernetic = {}, global.react));
+})(this, (function (exports, react) { 'use strict';
 
     // src/ApiClient.ts
     // HTTP client for AsterMind backend API
@@ -2663,6 +2663,555 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
         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
     /**
@@ -2705,15 +3254,28 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
      * 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
@@ -2984,22 +3546,35 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
             }
             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;
                 }
@@ -3396,6 +3971,124 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
         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
@@ -4032,6 +4725,284 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
         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] = react.useState({
+            entries: [],
+            isDiscovering: false,
+            error: null,
+            framework: null
+        });
+        const discoveredRef = react.useRef(false);
+        const optionsRef = react.useRef(options);
+        optionsRef.current = options;
+        /**
+         * Detect JavaScript framework
+         */
+        const detectFramework = react.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 = react.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 = react.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 = react.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 = react.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 = react.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 = react.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
+        react.useEffect(() => {
+            if (!enabled || discoveredRef.current)
+                return;
+            const timer = setTimeout(discoverRoutes, 100);
+            return () => clearTimeout(timer);
+        }, [enabled, discoverRoutes]);
+        // Re-discover on location changes (for SPAs)
+        react.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
@@ -5437,8 +6408,10 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
     exports.LicenseManager = LicenseManager;
     exports.OmegaOfflineRAG = OmegaOfflineRAG;
     exports.REQUIRED_FEATURES = REQUIRED_FEATURES;
+    exports.SiteMapDiscovery = SiteMapDiscovery;
     exports.configLoaders = configLoaders;
     exports.createClient = createClient;
+    exports.createDiscoveryConfig = createDiscoveryConfig;
     exports.createLicenseManager = createLicenseManager;
     exports.detectEnvironment = detectEnvironment;
     exports.getEnforcementMode = getEnforcementMode;
@@ -5446,6 +6419,7 @@ LJ5AZXvOhHaXdHzMuYKX5BpK4w7TqbPvJ6QPvKmLKvHh1VKcUJ6mJQgJJw==
     exports.isValidJWTFormat = isValidJWTFormat;
     exports.loadConfig = loadConfig;
     exports.registerAgenticCapabilities = registerAgenticCapabilities;
+    exports.useSiteMapDiscovery = useSiteMapDiscovery;
     exports.validateConfig = validateConfig;
     exports.verifyLicenseToken = verifyLicenseToken;