vanilla-agent 1.2.0 → 1.4.0

package/README.md

@@ -49,6 +49,7 @@ createAgentExperience(inlineHost, {
 // Floating launcher with runtime updates
 const controller = initAgentWidget({
   target: '#launcher-root',
+  windowKey: 'chatController', // Optional: stores controller on window.chatController
   config: {
     ...DEFAULT_WIDGET_CONFIG,
     apiUrl: proxyUrl,
@@ -69,12 +70,26 @@ controller.update({
 });
 ```
 
+### Initialization options
+
+`initAgentWidget` accepts the following options:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `target` | `string \| HTMLElement` | CSS selector or element where widget mounts. |
+| `config` | `AgentWidgetConfig` | Widget configuration object (see [Configuration reference](#configuration-reference) below). |
+| `useShadowDom` | `boolean` | Use Shadow DOM for style isolation (default: `true`). |
+| `onReady` | `() => void` | Callback fired when widget is initialized. |
+| `windowKey` | `string` | If provided, stores the controller on `window[windowKey]` for global access. Automatically cleaned up on `destroy()`. |
+
 > **Security note:** When you return HTML from `postprocessMessage`, make sure you sanitise it before injecting into the page. The provided postprocessors (`markdownPostprocessor`, `directivePostprocessor`) do not perform sanitisation.
 
 
 ### Programmatic control
 
-`initAgentWidget` (and `createAgentExperience`) return a controller with `open()`, `close()`, and `toggle()` helpers so you can launch the widget from your own UI elements.
+`initAgentWidget` (and `createAgentExperience`) return a controller with methods to programmatically control the widget.
+
+#### Basic controls
 
 ```ts
 const chat = initAgentWidget({
@@ -84,8 +99,129 @@ const chat = initAgentWidget({
 
 document.getElementById('open-chat')?.addEventListener('click', () => chat.open())
 document.getElementById('toggle-chat')?.addEventListener('click', () => chat.toggle())
+document.getElementById('close-chat')?.addEventListener('click', () => chat.close())
+```
+
+#### Message hooks
+
+You can programmatically set messages, submit messages, and control voice recognition:
+
+```ts
+const chat = initAgentWidget({
+  target: '#launcher-root',
+  config: { /* ... */ }
+})
+
+// Set a message in the input field (doesn't submit)
+chat.setMessage("Hello, I need help")
+
+// Submit a message (uses textarea value if no argument provided)
+chat.submitMessage()
+// Or submit a specific message
+chat.submitMessage("What are your hours?")
+
+// Start voice recognition
+chat.startVoiceRecognition()
+
+// Stop voice recognition
+chat.stopVoiceRecognition()
+```
+
+All hook methods return `boolean` indicating success (`true`) or failure (`false`). They will automatically open the widget if it's currently closed (when launcher is enabled).
+
+#### Clear chat
+
+```ts
+const chat = initAgentWidget({
+  target: '#launcher-root',
+  config: { /* ... */ }
+})
+
+// Clear all messages programmatically
+chat.clearChat()
+```
+
+#### Accessing from window
+
+To access the controller globally (e.g., from browser console or external scripts), use the `windowKey` option:
+
+```ts
+const chat = initAgentWidget({
+  target: '#launcher-root',
+  windowKey: 'chatController', // Stores controller on window.chatController
+  config: { /* ... */ }
+})
+
+// Now accessible globally
+window.chatController.setMessage("Hello from console!")
+window.chatController.submitMessage("Test message")
+window.chatController.startVoiceRecognition()
+```
+
+#### Message Types
+
+The widget uses `AgentWidgetMessage` objects to represent messages in the conversation. You can access these through `postprocessMessage` callbacks or by inspecting the session's message array.
+
+```typescript
+type AgentWidgetMessage = {
+  id: string;                    // Unique message identifier
+  role: "user" | "assistant" | "system";
+  content: string;               // Message text content
+  createdAt: string;             // ISO timestamp
+  streaming?: boolean;           // Whether message is still streaming
+  variant?: "assistant" | "reasoning" | "tool";
+  sequence?: number;             // Message ordering
+  reasoning?: AgentWidgetReasoning;
+  toolCall?: AgentWidgetToolCall;
+  tools?: AgentWidgetToolCall[];
+  viaVoice?: boolean;            // Indicates if user message was sent via voice input
+};
+```
+
+**`viaVoice` field**: Set to `true` when a user message is sent through voice recognition. This allows you to implement voice-specific behaviors, such as automatically reactivating voice recognition after assistant responses. You can check this field in your `postprocessMessage` callback:
+
+```ts
+postprocessMessage: ({ message, text, streaming }) => {
+  if (message.role === 'user' && message.viaVoice) {
+    console.log('User sent message via voice');
+  }
+  return text;
+}
 ```
 
+Alternatively, manually assign the controller:
+
+```ts
+const chat = initAgentWidget({ /* ... */ })
+window.chatController = chat
+```
+
+### Events
+
+The widget dispatches custom events that you can listen to for integration with your application:
+
+#### `vanilla-agent:clear-chat`
+
+Dispatched when the user clicks the "Clear chat" button or when `chat.clearChat()` is called programmatically.
+
+```ts
+window.addEventListener("vanilla-agent:clear-chat", (event) => {
+  console.log("Chat cleared at:", event.detail.timestamp);
+  // Clear your localStorage, reset state, etc.
+});
+```
+
+**Event detail:**
+- `timestamp`: ISO timestamp string of when the chat was cleared
+
+**Use cases:**
+- Clear localStorage chat history
+- Reset application state
+- Track analytics events
+- Sync with backend
+
+**Note:** The widget automatically clears the `"vanilla-agent-chat-history"` localStorage key by default when chat is cleared. If you set `clearChatHistoryStorageKey` in the config, it will also clear that additional key. You can still listen to this event for additional custom behavior.
+
 ### Travrse adapter
 
 This package ships with a Travrse adapter by default. The proxy handles all flow configuration, keeping the client lightweight and flexible.
@@ -130,7 +266,9 @@ The easiest way is to use the automatic installer script. It handles loading CSS
       theme: {
         accent: '#2563eb',
         surface: '#ffffff'
-      }
+      },
+      // Optional: configure stream parser for JSON/XML responses
+      // streamParser: () => window.AgentWidget.createJsonStreamParser()
     }
   };
 </script>
@@ -175,8 +313,9 @@ For more control, manually load CSS and JavaScript:
 
 <!-- Initialize widget -->
 <script>
-  window.AgentWidget.initAgentWidget({
+  const chatController = window.AgentWidget.initAgentWidget({
     target: '#vanilla-agent-anchor', // or 'body' for floating launcher
+    windowKey: 'chatWidget', // Optional: stores controller on window.chatWidget
     config: {
       apiUrl: '/api/chat/dispatch',
       launcher: {
@@ -187,9 +326,14 @@ For more control, manually load CSS and JavaScript:
       theme: {
         accent: '#111827',
         surface: '#f5f5f5'
-      }
+      },
+      // Optional: configure stream parser for JSON/XML responses
+      streamParser: window.AgentWidget.createJsonStreamParser // or createXmlParser, createPlainTextParser
     }
   });
+  
+  // Controller is now available as window.chatWidget (if windowKey was used)
+  // or use the returned chatController variable
 </script>
 ```
 
@@ -206,7 +350,14 @@ Replace `VERSION` with `latest` for auto-updates, or a specific version like `0.
 - `index.global.js` - Widget JavaScript (IIFE format)
 - `install.global.js` - Automatic installer script
 
-The script build exposes a `window.AgentWidget` global with `initAgentWidget()` and other exports.
+The script build exposes a `window.AgentWidget` global with `initAgentWidget()` and other exports, including parser functions:
+
+- `window.AgentWidget.initAgentWidget()` - Initialize the widget
+- `window.AgentWidget.createPlainTextParser()` - Plain text parser (default)
+- `window.AgentWidget.createJsonStreamParser()` - JSON parser using schema-stream
+- `window.AgentWidget.createXmlParser()` - XML parser
+- `window.AgentWidget.markdownPostprocessor()` - Markdown postprocessor
+- `window.AgentWidget.directivePostprocessor()` - Directive postprocessor
 
 ### Using default configuration
 
@@ -254,12 +405,179 @@ This ensures all configuration values are set to sensible defaults while allowin
 | `initialMessages` | `AgentWidgetMessage[]` | Seed the conversation transcript. |
 | `suggestionChips` | `string[]` | Render quick reply buttons above the composer. |
 | `postprocessMessage` | `(ctx) => string` | Transform message text before it renders (return HTML). Combine with `markdownPostprocessor` for rich output. |
+| `streamParser` | `() => AgentWidgetStreamParser` | Custom stream parser for detecting formats and extracting text from streaming responses. Handles JSON, XML, or custom formats. See [Stream Parser Configuration](#stream-parser-configuration) below. |
+| `clearChatHistoryStorageKey` | `string` | Additional localStorage key to clear when the clear chat button is clicked. The widget automatically clears `"vanilla-agent-chat-history"` by default. Use this option to clear additional keys (e.g., if you're using a custom storage key). |
 | `formEndpoint` | `string` | Endpoint used by built-in directives (defaults to `/form`). |
 | `launcherWidth` | `string` | CSS width applied to the floating launcher panel (e.g. `320px`, `90vw`). Defaults to `min(400px, calc(100vw - 24px))`. |
 | `debug` | `boolean` | Emits verbose logs to `console`. |
 
 All options are safe to mutate via `initAgentWidget(...).update(newConfig)`.
 
+### Stream Parser Configuration
+
+The widget can parse structured responses (JSON, XML, etc.) that stream in chunk by chunk, extracting the `text` field for display. By default, it uses a schema-stream based JSON parser. You can provide a custom parser to handle different formats, structures, or parsing strategies.
+
+**Key benefits of the unified stream parser:**
+- **Format detection**: Automatically detects if content matches your parser's format
+- **Extensible**: Handle JSON, XML, or any custom structured format
+- **Incremental parsing**: Extract text as it streams in, not just when complete
+
+**Using built-in parsers with ESM/Modules:**
+
+```javascript
+import { initAgentWidget, createPlainTextParser, createJsonStreamParser, createXmlParser } from 'vanilla-agent';
+
+const controller = initAgentWidget({
+  target: '#chat-root',
+  config: {
+    apiUrl: '/api/chat/dispatch',
+    streamParser: createJsonStreamParser // Use JSON parser
+    // Or: createXmlParser for XML, createPlainTextParser for plain text (default)
+  }
+});
+```
+
+**Using built-in parsers with CDN Script Tags:**
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/vanilla-agent@latest/dist/index.global.js"></script>
+<script>
+  window.AgentWidget.initAgentWidget({
+    target: '#chat-root',
+    config: {
+      apiUrl: '/api/chat/dispatch',
+      streamParser: window.AgentWidget.createJsonStreamParser // JSON parser
+      // Or: window.AgentWidget.createXmlParser for XML
+      // Or: window.AgentWidget.createPlainTextParser for plain text (default)
+    }
+  });
+</script>
+```
+
+**Using with automatic installer script:**
+
+```html
+<script>
+  window.siteAgentConfig = {
+    target: 'body',
+    config: {
+      apiUrl: '/api/chat/dispatch',
+      // Note: streamParser must be set after the script loads, or use a function
+      streamParser: function() {
+        return window.AgentWidget.createJsonStreamParser();
+      }
+    }
+  };
+</script>
+<script src="https://cdn.jsdelivr.net/npm/vanilla-agent@latest/dist/install.global.js"></script>
+```
+
+Alternatively, you can set it after the script loads:
+
+```html
+<script>
+  window.siteAgentConfig = {
+    target: 'body',
+    config: {
+      apiUrl: '/api/chat/dispatch'
+    }
+  };
+</script>
+<script src="https://cdn.jsdelivr.net/npm/vanilla-agent@latest/dist/install.global.js"></script>
+<script>
+  // Set parser after AgentWidget is loaded
+  if (window.siteAgentConfig && window.AgentWidget) {
+    window.siteAgentConfig.config.streamParser = window.AgentWidget.createJsonStreamParser;
+  }
+</script>
+```
+
+**Custom JSON parser example:**
+
+```javascript
+const jsonParser = () => {
+  let extractedText = null;
+  
+  return {
+    // Extract text field from JSON as it streams in
+    // Return null if not JSON or text not available yet
+    processChunk(accumulatedContent) {
+      const trimmed = accumulatedContent.trim();
+      // Return null if not JSON format
+      if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+        return null;
+      }
+      
+      const match = accumulatedContent.match(/"text"\s*:\s*"([^"]*(?:\\.[^"]*)*)"/);
+      if (match) {
+        extractedText = match[1].replace(/\\"/g, '"').replace(/\\n/g, '\n');
+        return extractedText;
+      }
+      return null;
+    },
+    
+    getExtractedText() {
+      return extractedText;
+    }
+  };
+};
+
+const controller = initAgentWidget({
+  target: '#chat-root',
+  config: {
+    apiUrl: '/api/chat/dispatch',
+    streamParser: jsonParser
+  }
+});
+```
+
+**Custom XML parser example:**
+
+```javascript
+const xmlParser = () => {
+  let extractedText = null;
+  
+  return {
+    processChunk(accumulatedContent) {
+      // Return null if not XML format
+      if (!accumulatedContent.trim().startsWith('<')) {
+        return null;
+      }
+      
+      // Extract text from <text>...</text> tags
+      const match = accumulatedContent.match(/<text[^>]*>([\s\S]*?)<\/text>/);
+      if (match) {
+        extractedText = match[1];
+        return extractedText;
+      }
+      return null;
+    },
+    
+    getExtractedText() {
+      return extractedText;
+    }
+  };
+};
+```
+
+**Parser interface:**
+
+```typescript
+interface AgentWidgetStreamParser {
+  // Process a chunk and return extracted text (if available)
+  // Return null if the content doesn't match this parser's format or text is not yet available
+  processChunk(accumulatedContent: string): Promise<string | null> | string | null;
+  
+  // Get the currently extracted text (may be partial)
+  getExtractedText(): string | null;
+  
+  // Optional cleanup when parsing is complete
+  close?(): Promise<void> | void;
+}
+```
+
+The parser's `processChunk` method is called for each chunk. If the content matches your parser's format, return the extracted text. If it doesn't match (or text isn't available yet), return `null` and the content will be treated as plain text. This allows you to display the text value as it streams in without showing raw structured characters.
+
 ### Optional proxy server
 
 The proxy server handles flow configuration and forwards requests to Travrse. You can configure it in three ways: