@makemore/agent-frontend 1.8.0 → 2.0.1

package/README.md

@@ -1,11 +1,10 @@
 # Agent Frontend
 
-A standalone, zero-dependency chat widget for AI agents. Embed conversational AI into any website with a single script tag.
+A lightweight chat widget for AI agents built with Preact. Embed conversational AI into any website with a single script tag.
 
 <p align="center">
-  <img src="https://img.shields.io/badge/vanilla-JavaScript-yellow" alt="Vanilla JS">
-  <img src="https://img.shields.io/badge/size-~15kb-green" alt="Size">
-  <img src="https://img.shields.io/badge/dependencies-0-blue" alt="Zero Dependencies">
+  <img src="https://img.shields.io/badge/Preact-673AB8?logo=preact&logoColor=white" alt="Preact">
+  <img src="https://img.shields.io/badge/size-~25kb-green" alt="Size">
   <img src="https://img.shields.io/badge/license-MIT-purple" alt="MIT License">
 </p>
 
@@ -13,10 +12,11 @@ A standalone, zero-dependency chat widget for AI agents. Embed conversational AI
 
 Most chat widgets are tightly coupled to specific frameworks or require complex build setups. Agent Frontend is different:
 
-- **Zero dependencies** - Pure vanilla JavaScript, no React/Vue/Angular required
+- **Lightweight** - Built with Preact (~3kb) for minimal bundle size
 - **CSS isolated** - Won't conflict with your existing styles (uses `all: initial` reset)
 - **SSE streaming** - Real-time token-by-token responses, not polling
 - **Production ready** - Session management, error handling, conversation persistence
+- **Component-based** - Clean architecture with hooks for state management
 
 ## Features
 
@@ -174,6 +174,7 @@ See `django-tts-example.py` for the complete Django backend implementation.
 | `showTTSButton` | boolean | `true` | Show TTS toggle button in header |
 | `showVoiceSettings` | boolean | `true` | Show voice settings button in header (works with proxy and direct API) |
 | `showExpandButton` | boolean | `true` | Show expand/minimize button in header |
+| `showConversationSidebar` | boolean | `true` | Show conversation history sidebar with hamburger menu |
 | `onEvent` | function | `null` | Callback for SSE events: `(eventType, payload) => void` |
 | `authStrategy` | string | `null` | Auth strategy: `'token'`, `'jwt'`, `'session'`, `'anonymous'`, `'none'` (auto-detected if null) |
 | `authToken` | string | `null` | Token value for `'token'` or `'jwt'` strategies |
@@ -574,6 +575,12 @@ ChatWidget.send('Hello, I need help!');
 // Clear the conversation
 ChatWidget.clearMessages();
 
+// Conversation sidebar controls
+ChatWidget.toggleSidebar();  // Open/close conversation sidebar
+ChatWidget.newConversation();  // Start a new conversation
+ChatWidget.switchConversation('conversation-id');  // Switch to a specific conversation
+ChatWidget.loadMoreMessages();  // Load older messages
+
 // Text-to-speech controls
 ChatWidget.toggleTTS();  // Toggle TTS on/off
 ChatWidget.stopSpeech(); // Stop current speech and clear queue
@@ -728,9 +735,135 @@ agent-frontend/
 
 Requires: `EventSource` (SSE), `fetch`, `localStorage`
 
+## Multiple Instances
+
+You can create multiple independent chat widgets on the same page using `createInstance()`:
+
+### Basic Multi-Instance Setup
+
+```html
+<div id="chat-1" style="width: 400px; height: 500px;"></div>
+<div id="chat-2" style="width: 400px; height: 500px;"></div>
+
+<script>
+  // Create first widget
+  const widget1 = ChatWidget.createInstance({
+    containerId: 'chat-1',
+    backendUrl: 'https://your-api.com',
+    agentKey: 'support-agent',
+    title: 'Support Chat',
+    primaryColor: '#0066cc',
+    embedded: true,
+  });
+
+  // Create second widget
+  const widget2 = ChatWidget.createInstance({
+    containerId: 'chat-2',
+    backendUrl: 'https://your-api.com',
+    agentKey: 'sales-agent',
+    title: 'Sales Chat',
+    primaryColor: '#00cc66',
+    embedded: true,
+  });
+</script>
+```
+
+### Instance Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `containerId` | string | `null` | ID of the container element for embedded mode |
+| `embedded` | boolean | `false` | If true, renders inline in container instead of floating |
+| `metadata` | object | `{}` | Custom metadata to send with each request |
+
+### Instance Methods
+
+Each instance returned by `createInstance()` has its own methods:
+
+```javascript
+const widget = ChatWidget.createInstance({ ... });
+
+// Control the widget
+widget.open();
+widget.close();
+widget.send('Hello!');
+widget.clearMessages();
+
+// TTS controls
+widget.toggleTTS();
+widget.stopSpeech();
+
+// Authentication
+widget.setAuth({ strategy: 'jwt', token: 'new-token' });
+widget.clearAuth();
+
+// Get state/config
+const state = widget.getState();
+const config = widget.getConfig();
+
+// Destroy the widget
+widget.destroy();
+```
+
+### Managing Multiple Instances
+
+```javascript
+// Get a specific instance by ID
+const widget = ChatWidget.getInstance('cw-1');
+
+// Get all instances
+const allWidgets = ChatWidget.getAllInstances();
+
+// Destroy all instances
+ChatWidget.getAllInstances().forEach(w => w.destroy());
+```
+
+### Embedded vs Floating Mode
+
+**Embedded Mode** (`embedded: true`):
+- Widget renders inside the specified container
+- No floating button or close button
+- Widget is always visible
+- Perfect for split-pane layouts, dashboards, or dedicated chat pages
+
+**Floating Mode** (`embedded: false`, default):
+- Widget appears as a floating button in the corner
+- Clicking opens the chat panel
+- Has close and expand buttons
+- Traditional chat widget behavior
+
+### Storage Isolation
+
+Each embedded instance uses isolated localStorage keys based on `containerId`:
+- `chat_widget_conversation_id_chat-1` for widget in `#chat-1`
+- `chat_widget_conversation_id_chat-2` for widget in `#chat-2`
+
+This ensures conversations don't get mixed up between instances.
+
 ## Version History
 
-### v1.4.0 (Latest)
+### v2.0.1 (Latest)
+- 🔄 **Preact Rewrite**: Complete rewrite using Preact for better maintainability
+- 🧩 **Component Architecture**: Modular components (ChatWidget, Header, InputForm, Message, MessageList, Sidebar)
+- 🪝 **React-style Hooks**: useChat and useModels hooks for state management
+- 🎛️ **Model Selector**: Built-in model selection dropdown
+- 📦 **Smaller Bundle**: Optimized build with esbuild
+- 🔧 **Better Developer Experience**: Watch mode, source maps, cleaner code structure
+
+### v1.10.1
+- 📚 **Conversation Sidebar**: Browse and switch between past conversations via hamburger menu
+- 📜 **Message Pagination**: Load older messages with "load more" functionality
+- 🔐 **CSRF Support**: Automatic CSRF token handling for Django session auth
+- ➕ **New Conversation**: Start fresh conversations from the sidebar
+- 🔄 **Auto-restore**: Automatically loads messages when returning to a conversation
+
+### v1.5.0
+- 🔀 **Multiple Instances**: Create multiple independent chat widgets on the same page
+- 📦 **Embedded Mode**: Render widgets inline in containers for dashboards and split-pane layouts
+- 🔒 **Storage Isolation**: Each instance has isolated localStorage for conversations
+- 🎯 **Instance API**: Full control over individual widget instances
+
+### v1.4.0
 - ✨ **Text-to-Speech**: ElevenLabs integration with secure Django proxy support
 - 🔊 Automatic speech for assistant and simulated user messages
 - 🎛️ Smart speech queuing to prevent overlap
@@ -760,4 +893,4 @@ Requires: `EventSource` (SSE), `fetch`, `localStorage`
 
 ## License
 
-MIT © 2024
+MIT © 2025