` element makes it trivial to plug in any client-side highlighter:\n\n```tsx\n// Example with Prism (consumer-installed)\nimport Prism from 'prismjs';\nimport 'prismjs/components/prism-python';\n\nuseEffect(() => {\n Prism.highlightAll();\n}, [messages]);\n```\n\n### Theming code blocks\n\nTwo CSS variables control the default code-block appearance:\n\n```css\n:root {\n --astermind-code-bg: #1e1e2e; /* dark slate */\n --astermind-code-fg: #f8f8f2; /* soft white */\n}\n```\n\nOverride them to match your site's syntax theme. If you'd rather restyle the whole element, target `.astermind-code-block`.\n\n---\n\n## Source Citations\n\nWhen the AsterMind backend returns sources alongside an assistant reply, the widget renders a collapsible \"Sources\" toggle under the message.\n\n### Capping the number of sources\n\nTo avoid runaway lists when an upstream response carries an oversized source array, the widget caps the number of citations rendered per message at **7 by default**. Override with `SourceDisplayConfig.maxSources`:\n\n```tsx\n\n```\n\n- `0` (or any negative number) hides the sources toggle entirely.\n- The count label reflects the **displayed** (capped) count, not the raw length.\n\n---\n\n## React Hooks API\n\n### useCybernetic\n\nDirect API client access for custom implementations:\n\n```tsx\nimport { useCybernetic } from '@astermind/evo-virtual-assistant-template';\n\nfunction MyComponent() {\n const {\n sendMessage, // Send a message (non-streaming)\n sendMessageStream, // Send a message (streaming)\n connectionStatus, // 'online' | 'offline' | 'connecting' | 'error'\n isProcessing, // Whether a request is in progress\n lastError, // Last error that occurred\n sessionId, // Current session ID\n clearSession, // Clear the current session\n syncCache, // Sync cache for offline use\n client // Underlying CyberneticClient instance\n } = useCybernetic({\n apiUrl: 'https://api.example.com',\n apiKey: 'am_your-api-key'\n });\n\n const handleSend = async () => {\n const response = await sendMessage('Hello!');\n console.log(response.reply, response.sources);\n };\n}\n```\n\n### useChat\n\nChat state management:\n\n```tsx\nimport { useChat } from '@astermind/evo-virtual-assistant-template';\n\nfunction MyComponent() {\n const {\n messages, // Array of chat messages\n addMessage, // Add a new message\n updateMessage, // Update an existing message\n clearMessages, // Clear all messages\n pendingAction, // Currently pending agent action\n setPendingAction // Set pending action\n } = useChat();\n}\n```\n\n### useTheme\n\nTheme customization hook:\n\n```tsx\nimport { useTheme } from '@astermind/evo-virtual-assistant-template';\n\nfunction MyComponent() {\n const { theme, cssVariables } = useTheme({\n primaryColor: '#10B981',\n borderRadius: '16px'\n });\n\n return ...
;\n}\n```\n\n### useScrollToBottom\n\nAuto-scroll behavior for message lists:\n\n```tsx\nimport { useScrollToBottom } from '@astermind/evo-virtual-assistant-template';\n\nfunction MessageList({ messages }) {\n const { containerRef, scrollToBottom } = useScrollToBottom();\n\n return (\n \n {messages.map(msg => )}\n
\n );\n}\n```\n\n---\n\n## Components API\n\nAll components are exported for custom compositions:\n\n```tsx\nimport {\n VirtualAssistantWidget, // Main widget (includes bubble + window)\n ChatBubble, // Floating trigger button\n ChatWindow, // Chat window container\n ChatHeader, // Window header with title/subtitle\n ChatInput, // Message input with send button\n MessageList, // Scrollable message container\n MessageBubble, // Individual message bubble\n ActionCard, // Agentic action confirmation card\n SourceCitation, // Source reference component\n StatusIndicator, // Connection status display\n TypingIndicator // Typing/loading animation\n} from '@astermind/evo-virtual-assistant-template';\n```\n\n---\n\n## TypeScript Support\n\nFull TypeScript support with exported types:\n\n```typescript\nimport type {\n // Template-specific types\n AsterMindVirtualAssistantProps,\n VirtualAssistantTheme,\n ChatMessage,\n AgentAction,\n ChatState,\n WidgetPosition,\n AgentConfig,\n FallbackConfig,\n SiteMapEntry,\n VanillaInitConfig,\n SendOptions,\n\n // Re-exported from @astermind/evo-virtual-assistant-client\n CyberneticConfig,\n CyberneticResponse,\n CyberneticError,\n Source,\n ConnectionStatus,\n ConfidenceLevel,\n StreamCallbacks,\n AskOptions,\n CachedDocument,\n CacheStatus,\n AgenticConfig\n} from '@astermind/evo-virtual-assistant-template';\n\n// CyberneticClient class is also re-exported for advanced usage\nimport { CyberneticClient } from '@astermind/evo-virtual-assistant-template';\n```\n\n---\n\n## Troubleshooting\n\n### Widget not appearing\n\n1. Ensure styles are imported: `import '@astermind/evo-virtual-assistant-template/styles'`\n2. Check that `apiUrl` and `apiKey` are provided\n3. Verify the widget container has `position: relative` or is in the document flow\n\n### Connection errors\n\n1. Check that your `apiUrl` is correct and accessible\n2. Verify your API key is valid and has the correct permissions\n3. Check browser console for CORS errors - ensure your backend allows the origin\n\n### Streaming not working\n\n1. Verify your backend supports the `/api/external/chat/stream` endpoint\n2. Check that SSE is not being blocked by proxies or firewalls\n3. Ensure `Content-Type: text/event-stream` header is set on responses\n\n### Actions not executing\n\n1. Confirm `agent.enabled` is set to `true`\n2. Check that actions meet the `confidenceThreshold`\n3. Verify custom action handlers are properly defined\n\n### Styles not applying\n\n1. Ensure the CSS file is loaded before the JS\n2. Check for CSS specificity conflicts with your existing styles\n3. Use `!important` or increase specificity if needed\n\n### White text on white background (Dark Mode / CSS Framework conflicts)\n\nIf you're using Tailwind CSS, Bootstrap, or any CSS framework that applies global dark mode styles (e.g. `body { color: white }` or `dark:text-gray-100`), those styles can bleed into the virtual assistant widget through CSS inheritance. This commonly causes the chat input textarea to show white text on a white background.\n\n**Fix: Add these overrides in your app's CSS** (after importing the virtual assistant styles):\n\n```css\n/* Isolate virtual assistant widget from host page dark mode */\n.astermind-window {\n color: var(--astermind-text, #1f2937);\n background: var(--astermind-background, #ffffff);\n}\n\n.astermind-input__textarea {\n color: var(--astermind-text, #1f2937) !important;\n background-color: var(--astermind-background, #ffffff) !important;\n}\n\n.astermind-input__textarea::placeholder {\n color: var(--astermind-text-muted, #6b7280) !important;\n}\n```\n\nThe `!important` is needed on the textarea because CSS frameworks often set `color: inherit` on form elements, which inherits from the host page's dark mode text color. The `.astermind-window` rule establishes the widget's own color context.\n\nIf you're using custom theme colors, the CSS variables will be set by the `theme` prop and the overrides above will automatically use your custom values.\n\n---\n\n## Browser Support\n\n| Browser | Version |\n|---------|---------|\n| Chrome | 80+ |\n| Firefox | 75+ |\n| Safari | 13+ |\n| Edge | 80+ |\n\nThe standalone bundle includes necessary polyfills for broader compatibility.\n\n---\n\n## Build Outputs\n\n| File | Format | Description |\n|------|--------|-------------|\n| `evo-virtual-assistant.esm.js` | ESM | ES Module for bundlers (tree-shakeable) |\n| `evo-virtual-assistant.umd.js` | UMD | Universal Module Definition |\n| `evo-virtual-assistant.min.js` | IIFE | Standalone bundle with React included |\n| `evo-virtual-assistant.css` | CSS | Compiled and minified styles |\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\nBuilt with care by the [AsterMind](https://astermind.ai) team.\n","readmeFilename":"README.md"}