@convai/web-sdk 0.3.1-beta.3 → 0.3.2-beta.0

package/README.md

@@ -1,47 +1,6 @@
 # @convai/web-sdk
 
-[![npm version](https://badge.fury.io/js/%40convai%2Fweb-sdk.svg)](https://www.npmjs.com/package/@convai/web-sdk)
-
-JavaScript/TypeScript SDK for building AI voice assistants with real-time audio/video streaming. Drop-in widgets for **React** and **Vanilla JavaScript/TypeScript** with customizable UI components.
-
----
-
-## 📑 Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-  - [React - ConvaiWidget](#react---convaiwidget)
-  - [Vanilla JS/TS - ConvaiWidget](#vanilla-jsts---convaiwidget)
-- [Core Concepts](#core-concepts)
-- [React SDK](#react-sdk)
-  - [useConvaiClient Hook](#useconvaiclient-hook)
-  - [AudioRenderer Component](#audiorenderer-component)
-  - [AudioContext](#audiocontext)
-  - [React Exports Reference](#react-exports-reference)
-- [Vanilla SDK](#vanilla-sdk)
-  - [ConvaiClient Class](#convaiclient-class)
-  - [AudioRenderer Class](#audiorenderer-class)
-  - [Vanilla Exports Reference](#vanilla-exports-reference)
-- [Video & Screen Share](#video--screen-share)
-  - [Critical Requirements](#critical-requirements)
-  - [Enabling Video](#enabling-video)
-  - [Enabling Screen Share](#enabling-screen-share)
-- [Building Custom UIs](#building-custom-uis)
-  - [Custom Chat Interface](#custom-chat-interface)
-  - [Audio Visualizer](#audio-visualizer)
-  - [Message Types](#message-types)
-- [API Reference](#api-reference)
-  - [Configuration](#configuration)
-  - [Connection Management](#connection-management)
-  - [Messaging](#messaging)
-  - [Audio Controls](#audio-controls)
-  - [Video Controls](#video-controls)
-  - [Screen Share Controls](#screen-share-controls)
-- [Getting Credentials](#getting-credentials)
-- [TypeScript Support](#typescript-support)
-- [Support](#support)
-
----
+JavaScript/TypeScript SDK for Convai AI voice assistants. Build voice-powered AI interactions for web applications with real-time audio/video streaming. Supports both React and Vanilla JavaScript/TypeScript.
 
 ## Installation
 
@@ -49,25 +8,14 @@ JavaScript/TypeScript SDK for building AI voice assistants with real-time audio/
 npm install @convai/web-sdk
 ```
 
-**Peer Dependencies (React only):**
+## Basic Setup
 
-```bash
-npm install react@^18.0.0 react-dom@^18.0.0
-```
-
----
-
-## Quick Start
-
-### React - ConvaiWidget
-
-The `ConvaiWidget` is a complete, pre-built chat interface with voice/video capabilities.
+### React
 
 ```tsx
-import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
 
 function App() {
-  // Initialize the Convai client
   const convaiClient = useConvaiClient({
     apiKey: "your-api-key",
     characterId: "your-character-id",
@@ -77,169 +25,7 @@ function App() {
 }
 ```
 
-**That's it!** The widget auto-connects on first user interaction and handles all UI/audio for you.
-
----
-
-## 🤖 For AI Code Generators (v0, Lovable, Bolt, etc.)
-
-**If you're using an AI coding assistant to add Convai to your project, use this exact template to avoid errors:**
-
-### Copy-Paste Template (Works Every Time)
-
-```tsx
-import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
-
-export default function App() {
-  // Step 1: Create the client with your credentials
-  const convaiClient = useConvaiClient({
-    apiKey: "your-api-key-here",
-    characterId: "your-character-id-here",
-  });
-
-  // Step 2: Pass ONLY the client to the widget
-  return <ConvaiWidget convaiClient={convaiClient} />;
-}
-```
-
-### Common Mistakes AI Tools Make
-
-❌ **DON'T DO THIS:**
-
-```tsx
-// Wrong: Passing props directly to ConvaiWidget
-<ConvaiWidget apiKey="..." characterId="..." />
-
-// Wrong: Stringifying the client
-<ConvaiWidget convaiClient={JSON.stringify(convaiClient)} />
-
-// Wrong: Spreading client properties
-<ConvaiWidget {...convaiClient} />
-
-// Wrong: Using client in string context
-const info = `Client: ${convaiClient}`; // "Cannot convert object to primitive value"
-
-// Wrong: Passing client through env vars
-const client = process.env.CONVAI_CLIENT; // This won't work
-```
-
-✅ **DO THIS:**
-
-```tsx
-// Correct: Client created in component, passed as object
-const convaiClient = useConvaiClient({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
-});
-
-return <ConvaiWidget convaiClient={convaiClient} />;
-```
-
-### If You Get "Cannot convert object to primitive value"
-
-This error means you're using the client object in a primitive context. Check for:
-
-1. **String concatenation:**
-
-   ```tsx
-   // ❌ Wrong
-   console.log("Client: " + convaiClient);
-
-   // ✅ Correct
-   console.log("Connected:", convaiClient.state.isConnected);
-   ```
-
-2. **Template literals:**
-
-   ```tsx
-   // ❌ Wrong
-   const text = `Client: ${convaiClient}`;
-
-   // ✅ Correct
-   const text = `Status: ${convaiClient.state.agentState}`;
-   ```
-
-3. **Using as a key:**
-
-   ```tsx
-   // ❌ Wrong
-   <div key={convaiClient}>...</div>
-
-   // ✅ Correct
-   <div key="convai-widget">...</div>
-   ```
-
-### Complete Working Example for AI Tools
-
-```tsx
-import React from "react";
-import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
-
-function App() {
-  // Initialize the client
-  const convaiClient = useConvaiClient({
-    apiKey: "your-api-key-here",
-    characterId: "your-character-id-here",
-    enableVideo: false, // Set to true if you need video
-  });
-
-  // Optional: Add debug logging
-  console.log("Convai client initialized:", !!convaiClient);
-  console.log("Connection status:", convaiClient?.state?.isConnected);
-
-  return (
-    <div style={{ width: "100vw", height: "100vh" }}>
-      <ConvaiWidget convaiClient={convaiClient} />
-    </div>
-  );
-}
-
-export default App;
-```
-
-### Prompt for AI Code Generators
-
-**Use this prompt to get correct code:**
-
-```
-Add Convai voice chat to this app using @convai/web-sdk.
-
-CRITICAL RULES:
-1. Import: import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
-2. Create client INSIDE component: const convaiClient = useConvaiClient({ apiKey: "...", characterId: "..." });
-3. Pass ONLY client to widget: <ConvaiWidget convaiClient={convaiClient} />
-4. DO NOT pass apiKey or characterId directly to ConvaiWidget
-5. DO NOT stringify, spread, or destructure the client object
-6. DO NOT use the client object in string contexts
-
-Example:
-const convaiClient = useConvaiClient({ apiKey: "KEY", characterId: "ID" });
-return <ConvaiWidget convaiClient={convaiClient} />;
-```
-
-### Video & Screen Share with AI Tools
-
-If you need video/screen share, add these TWO changes:
-
-```tsx
-// Step 1: Add enableVideo to client config
-const convaiClient = useConvaiClient({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
-  enableVideo: true, // ← Required for video features
-});
-
-// Step 2: Show controls in widget
-<ConvaiWidget
-  convaiClient={convaiClient}
-  showVideo={true} // ← Shows video button
-  showScreenShare={true} // ← Shows screen share button
-/>;
-```
-
-**Without `enableVideo: true`, video and screen share will NOT work even if you show the buttons.**
-
-### Vanilla JS/TS - ConvaiWidget
+### Vanilla TypeScript
 
 ```typescript
 import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
@@ -250,7 +36,7 @@ const client = new ConvaiClient({
   characterId: "your-character-id",
 });
 
-// Create and mount widget - auto-connects on first user click
+// Create widget - auto-connects on first user click
 const widget = createConvaiWidget(document.body, {
   convaiClient: client,
 });
@@ -259,1068 +45,770 @@ const widget = createConvaiWidget(document.body, {
 widget.destroy();
 ```
 
----
+## Exports
 
-## Core Concepts
+### React Exports (`@convai/web-sdk` or `@convai/web-sdk/react`)
 
-### The Architecture
+**Components:**
 
-```
-┌─────────────────────────────────────────────────┐
-│  ConvaiWidget (UI Layer)                       │
-│  ├─ Chat Interface                             │
-│  ├─ Voice Mode                                 │
-│  └─ Video/Screen Share UI                      │
-└─────────────────────────────────────────────────┘
-                     ▼
-┌─────────────────────────────────────────────────┐
-│  ConvaiClient (Core Logic)                     │
-│  ├─ Connection Management                      │
-│  ├─ Message Handling                           │
-│  ├─ State Management                           │
-│  └─ Audio/Video Controls                       │
-└─────────────────────────────────────────────────┘
-                     ▼
-┌─────────────────────────────────────────────────┐
-│  WebRTC Room (Communication Layer)             │
-│  ├─ Real-time Audio/Video Streaming            │
-│  ├─ Track Management                           │
-│  └─ Network Communication                      │
-└─────────────────────────────────────────────────┘
-                     ▼
-┌─────────────────────────────────────────────────┐
-│  AudioRenderer (Critical for Playback)         │
-│  ├─ Attaches audio tracks to DOM               │
-│  ├─ Manages audio elements                     │
-│  └─ Enables bot voice playback                 │
-└─────────────────────────────────────────────────┘
-```
+- `ConvaiWidget` - Main chat widget component
 
-### Key Principles
+**Hooks:**
 
-1. **ConvaiClient** - The brain. Manages connection, state, and communication with Convai servers.
-2. **AudioRenderer** - **CRITICAL**: Without this, you won't hear the bot. It renders audio to the user's speakers.
-3. **ConvaiWidget** - The complete UI. Uses both ConvaiClient and AudioRenderer internally.
-4. **Connection Type** - Determines capabilities:
-   - `"audio"` (default) - Audio only
-   - `"video"` - Audio + Video + Screen Share
+- `useConvaiClient(config?)` - Main client hook
+- `useCharacterInfo(characterId, apiKey)` - Fetch character metadata
+- `useLocalCameraTrack()` - Get local camera track
 
----
+**Core Client:**
 
-## React SDK
+- `ConvaiClient` - Core client class
 
-### useConvaiClient Hook
+**Types:**
 
-**Purpose**: Returns a fully configured `ConvaiClient` instance with reactive state updates.
-
-**When to Use**: Every React app using Convai needs this hook.
-
-**What It Does**:
-
-- Creates and manages a ConvaiClient instance
-- Provides reactive state (connection, messages, activity)
-- Handles connection lifecycle
-- Exposes audio/video/screen share controls
-
-```tsx
-import { useConvaiClient } from "@convai/web-sdk/react";
-
-function ChatbotWrapper() {
-  const convaiClient = useConvaiClient({
-    apiKey: "your-api-key",
-    characterId: "your-character-id",
-    enableVideo: false, // Default: audio only
-    startWithAudioOn: false, // Mic starts muted
-  });
+- `ConvaiConfig` - Configuration interface
+- `ConvaiClientState` - Client state interface
+- `ChatMessage` - Message interface
+- `IConvaiClient` - Client interface
+- `AudioControls` - Audio control interface
+- `VideoControls` - Video control interface
+- `ScreenShareControls` - Screen share control interface
 
-  // Access reactive state
-  const { state, chatMessages, userTranscription, isBotReady } = convaiClient;
+**Components:**
 
-  // Use controls
-  const handleMute = () => convaiClient.audioControls.muteAudio();
-  const handleSend = () =>
-    convaiClient.sendUserTextMessage("Hello, character!");
+- `AudioRenderer` - Audio playback component
+- `AudioContext` - Audio context provider
 
-  return (
-    <div>
-      <p>Status: {state.agentState}</p>
-      <p>Messages: {chatMessages.length}</p>
-      <button onClick={handleMute}>Mute</button>
-      <button onClick={handleSend}>Send</button>
-    </div>
-  );
-}
-```
+### Vanilla Exports (`@convai/web-sdk/vanilla`)
 
-### AudioRenderer Component
+**Functions:**
 
-**Purpose**: Renders remote audio tracks to the user's speakers.
+- `createConvaiWidget(container, options)` - Create widget instance
+- `destroyConvaiWidget(widget)` - Destroy widget instance
 
-**⚠️ CRITICAL**: Without `AudioRenderer`, you will NOT hear the bot's voice.
+**Classes:**
 
-**When to Use**:
+- `ConvaiClient` - Core client class
+- `AudioRenderer` - Audio playback handler
 
-- Always when building custom UIs
-- Already included in `ConvaiWidget` (no need to add separately)
+**Types:**
 
-**How It Works**:
+- `VanillaWidget` - Widget instance interface
+- `VanillaWidgetOptions` - Widget options interface
+- `IConvaiClient` - Client interface
+- `ConvaiConfig` - Configuration interface
+- `ConvaiClientState` - Client state interface
+- `ChatMessage` - Message interface
 
-- Attaches to the WebRTC room
-- Automatically creates `<audio>` elements for remote participants (the bot)
-- Manages audio playback lifecycle
+### Core Exports (`@convai/web-sdk/core`)
 
-```tsx
-import { useConvaiClient, AudioRenderer } from "@convai/web-sdk/react";
+**Classes:**
 
-function CustomChatUI() {
-  const convaiClient = useConvaiClient({
-    apiKey: "your-api-key",
-    characterId: "your-character-id",
-  });
+- `ConvaiClient` - Main client class
+- `AudioManager` - Audio management
+- `VideoManager` - Video management
+- `ScreenShareManager` - Screen share management
+- `MessageHandler` - Message handling
+- `EventEmitter` - Event emitter base class
 
-  return (
-    <div>
-      {/* CRITICAL: This component renders bot audio to speakers */}
-      <AudioRenderer />
-
-      {/* Your custom UI */}
-      <div>
-        {convaiClient.chatMessages.map((msg) => (
-          <div key={msg.id}>{msg.content}</div>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
+**Types:**
 
-### AudioContext
+- All types from React/Vanilla exports
+- `ConvaiClientType` - Type alias for ConvaiClient
 
-**Purpose**: Provides the WebRTC Room to child components.
+## Props and Configuration
 
-**When to Use**: When building deeply nested custom UIs that need direct access to the audio room.
-
-**How It Works**: React Context that holds the active WebRTC room.
+### ConvaiWidget Props (React)
 
 ```tsx
-import {
-  useConvaiClient,
-  AudioRenderer,
-  AudioContext,
-} from "@convai/web-sdk/react";
-import { useContext } from "react";
-
-function ChatbotWrapper() {
-  const convaiClient = useConvaiClient({
-    /* config */
-  });
-
-  return (
-    <AudioContext.Provider value={convaiClient.room}>
-      <AudioRenderer />
-      <ChildComponent />
-    </AudioContext.Provider>
-  );
-}
-
-function ChildComponent() {
-  const room = useContext(AudioContext);
-  // Access WebRTC room directly
-  console.log("Room state:", room?.state);
-  return <div>Child has access to Room</div>;
+interface ConvaiWidgetProps {
+  /** Convai client instance (required) */
+  convaiClient: IConvaiClient & {
+    activity?: string;
+    isAudioMuted: boolean;
+    isVideoEnabled: boolean;
+    isScreenShareActive: boolean;
+  };
+  /** Show video toggle button in settings (default: true) */
+  showVideo?: boolean;
+  /** Show screen share toggle button in settings (default: true) */
+  showScreenShare?: boolean;
 }
 ```
 
-### React Exports Reference
-
-```tsx
-// Components
-import { ConvaiWidget } from "@convai/web-sdk/react";
-
-// Hooks
-import { useConvaiClient, useCharacterInfo } from "@convai/web-sdk/react";
-
-// Audio Rendering (Critical)
-import { AudioRenderer, AudioContext } from "@convai/web-sdk/react";
-
-// Core Client (for advanced usage)
-import { ConvaiClient } from "@convai/web-sdk/react";
-
-// Types
-import type {
-  ConvaiConfig,
-  ConvaiClientState,
-  ChatMessage,
-  IConvaiClient,
-  AudioControls,
-  VideoControls,
-  ScreenShareControls,
-} from "@convai/web-sdk/react";
-```
-
----
-
-## Vanilla SDK
-
-### ConvaiClient Class
-
-**Purpose**: Core client for managing Convai connections in vanilla JavaScript/TypeScript.
-
-**When to Use**: Any non-React application or when you need full control.
-
-**What It Provides**:
-
-- Connection management
-- Message handling
-- State management (via events)
-- Audio/video/screen share controls
-
-```typescript
-import { ConvaiClient } from "@convai/web-sdk/vanilla";
-
-const client = new ConvaiClient({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
-});
-
-// Connect
-await client.connect();
-
-// Listen to events
-client.on("stateChange", (state) => {
-  console.log("Agent state:", state.agentState);
-});
-
-client.on("message", (message) => {
-  console.log("New message:", message.content);
-});
-
-// Send messages
-client.sendUserTextMessage("Hello!");
-
-// Control audio
-await client.audioControls.muteAudio();
-await client.audioControls.unmuteAudio();
-
-// Disconnect
-await client.disconnect();
-```
-
-### AudioRenderer Class
-
-**Purpose**: Manages audio playback for vanilla JavaScript/TypeScript applications.
-
-**⚠️ CRITICAL**: Without this, you will NOT hear the bot's voice.
-
-**When to Use**:
-
-- Always when building custom vanilla UIs
-- Already included in vanilla `ConvaiWidget` (no need to add separately)
-
-**How It Works**:
-
-- Attaches to the WebRTC room
-- Automatically creates hidden `<audio>` elements
-- Manages audio playback for remote participants (the bot)
-
-```typescript
-import { ConvaiClient, AudioRenderer } from "@convai/web-sdk/vanilla";
-
-const client = new ConvaiClient({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
-});
-
-await client.connect();
-
-// CRITICAL: Create AudioRenderer to hear bot audio
-const audioRenderer = new AudioRenderer(client.room);
-
-// Your custom UI logic...
-
-// Cleanup
-audioRenderer.destroy();
-await client.disconnect();
-```
-
-### ConvaiClient Returns
-
-The vanilla `ConvaiClient` returns the same interface as React's `useConvaiClient`:
+### createConvaiWidget Options (Vanilla)
 
 ```typescript
-const client = new ConvaiClient({ apiKey: "...", characterId: "..." });
-await client.connect();
-
-// State & Connection
-client.state.isConnected; // boolean
-client.state.agentState; // 'disconnected' | 'connected' | 'listening' | 'thinking' | 'speaking'
-client.isBotReady; // boolean - ready for messages
-
-// Convenience Properties (match React)
-client.isAudioMuted; // boolean - mic muted
-client.isVideoEnabled; // boolean - camera on
-client.isScreenShareActive; // boolean - sharing screen
-
-// Messages
-client.chatMessages; // ChatMessage[]
-client.userTranscription; // string
-
-// Controls
-client.audioControls.muteAudio();
-client.videoControls.enableVideo();
-client.screenShareControls.toggleScreenShare();
+interface VanillaWidgetOptions {
+  /** Convai client instance (required) */
+  convaiClient: IConvaiClient & {
+    activity?: string;
+    chatMessages: ChatMessage[];
+  };
+  /** Show video toggle button in settings (default: true) */
+  showVideo?: boolean;
+  /** Show screen share toggle button in settings (default: true) */
+  showScreenShare?: boolean;
+}
 ```
 
-### Vanilla Exports Reference
+### ConvaiConfig
 
 ```typescript
-// Widget
-import {
-  createConvaiWidget,
-  destroyConvaiWidget,
-} from "@convai/web-sdk/vanilla";
-
-// Core Client
-import { ConvaiClient } from "@convai/web-sdk/vanilla";
-
-// Audio Rendering (Critical)
-import { AudioRenderer } from "@convai/web-sdk/vanilla";
-
-// Lipsync Helpers (3D animation)
-import { ARKIT_BLENDSHAPE_NAMES } from "@convai/web-sdk/vanilla";
-
-// Types
-import type {
-  VanillaWidget,
-  VanillaWidgetOptions,
-  VanillaConvaiClient,
-  ConvaiConfig,
-  ConvaiClientState,
-  ChatMessage,
-  IConvaiClient,
-  AudioControls,
-  VideoControls,
-  ScreenShareControls,
-  BlendshapeFrame,
-  BlendshapeControls,
-} from "@convai/web-sdk/vanilla";
+interface ConvaiConfig {
+  /** Your Convai API key from convai.com dashboard (required) */
+  apiKey: string;
+  /** The Character ID to connect to (required) */
+  characterId: string;
+  /**
+   * End user identifier for speaker management (optional).
+   * When provided: enables long-term memory and analytics
+   * When not provided: anonymous mode, no persistent memory
+   */
+  endUserId?: string;
+  /** Custom Convai API URL (optional, defaults to production endpoint) */
+  url?: string;
+  /**
+   * Enable video capability (default: false).
+   * If true, connection_type will be "video" (supports audio, video, and screenshare).
+   * If false, connection_type will be "audio" (audio only).
+   */
+  enableVideo?: boolean;
+  /**
+   * Start with video camera on when connecting (default: false).
+   * Only works if enableVideo is true.
+   */
+  startWithVideoOn?: boolean;
+  /**
+   * Start with microphone on when connecting (default: false).
+   * If false, microphone stays off until user enables it.
+   */
+  startWithAudioOn?: boolean;
+  /** Enable text-to-speech audio generation (default: true) */
+  ttsEnabled?: boolean;
+}
 ```
 
----
-
-## Video & Screen Share
-
-### Critical Requirements
-
-> ⚠️ **IMPORTANT**: Video and Screen Share features require **TWO** configuration changes:
-
-#### 1. Set `enableVideo: true` in Client Configuration
-
-This sets the connection type to `"video"` which enables video capabilities.
-
-#### 2. Set `showVideo` and/or `showScreenShare` in Widget Props
-
-This shows the UI controls for video/screen share.
+## Features
 
-**Without both, video features will NOT work.**
+### Video Enabled Chat
 
----
+To enable video capabilities, set `enableVideo: true` in your configuration. This enables audio, video, and screen sharing.
 
-### Enabling Video
-
-#### React
+**React:**
 
 ```tsx
-import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
 
 function App() {
-  // ✅ STEP 1: Enable video in client config
   const convaiClient = useConvaiClient({
     apiKey: "your-api-key",
     characterId: "your-character-id",
-    enableVideo: true, // ← REQUIRED for video
+    enableVideo: true,
     startWithVideoOn: false, // Camera off by default
   });
 
   return (
     <ConvaiWidget
       convaiClient={convaiClient}
-      showVideo={true} // ← STEP 2: Show video controls
-      showScreenShare={false} // Optional: hide screen share
+      showVideo={true}
+      showScreenShare={true}
     />
   );
 }
 ```
 
-#### Vanilla
+**Vanilla:**
 
 ```typescript
 import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
 
-// ✅ STEP 1: Enable video in client config
 const client = new ConvaiClient({
   apiKey: "your-api-key",
   characterId: "your-character-id",
-  enableVideo: true, // ← REQUIRED for video
+  enableVideo: true,
   startWithVideoOn: false,
 });
 
 const widget = createConvaiWidget(document.body, {
   convaiClient: client,
-  showVideo: true, // ← STEP 2: Show video controls
-  showScreenShare: false,
+  showVideo: true,
+  showScreenShare: true,
 });
 ```
 
-#### Manual Video Control
+**Manual Video Controls:**
 
 ```typescript
-// Enable camera
+// Enable video camera
 await convaiClient.videoControls.enableVideo();
 
-// Disable camera
+// Disable video camera
 await convaiClient.videoControls.disableVideo();
 
-// Toggle camera
+// Toggle video
 await convaiClient.videoControls.toggleVideo();
 
-// Check state
-console.log(convaiClient.isVideoEnabled);
+// Check video state
+const isVideoEnabled = convaiClient.videoControls.isVideoEnabled;
 
 // Set video quality
 await convaiClient.videoControls.setVideoQuality("high"); // 'low' | 'medium' | 'high'
 
-// Get available cameras
+// Get available video devices
 const devices = await convaiClient.videoControls.getVideoDevices();
 
-// Switch camera
+// Set specific video device
 await convaiClient.videoControls.setVideoDevice(deviceId);
 ```
 
----
-
-### Enabling Screen Share
-
-Screen sharing **requires** `enableVideo: true` (connection type must be `"video"`).
-
-#### React
-
-```tsx
-import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
-
-function App() {
-  // ✅ STEP 1: Enable video (required for screen share)
-  const convaiClient = useConvaiClient({
-    apiKey: "your-api-key",
-    characterId: "your-character-id",
-    enableVideo: true, // ← REQUIRED for screen share
-  });
-
-  return (
-    <ConvaiWidget
-      convaiClient={convaiClient}
-      showVideo={true} // Optional: show video controls
-      showScreenShare={true} // ← STEP 2: Show screen share controls
-    />
-  );
-}
-```
-
-#### Vanilla
+**Screen Sharing:**
 
 ```typescript
-import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
-
-// ✅ STEP 1: Enable video (required for screen share)
-const client = new ConvaiClient({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
-  enableVideo: true, // ← REQUIRED for screen share
-});
-
-const widget = createConvaiWidget(document.body, {
-  convaiClient: client,
-  showVideo: true,
-  showScreenShare: true, // ← STEP 2: Show screen share controls
-});
-```
-
-#### Manual Screen Share Control
-
-```typescript
-// Start screen share
+// Enable screen share
 await convaiClient.screenShareControls.enableScreenShare();
 
-// Start screen share with audio
+// Enable screen share with audio
 await convaiClient.screenShareControls.enableScreenShareWithAudio();
 
-// Stop screen share
+// Disable screen share
 await convaiClient.screenShareControls.disableScreenShare();
 
 // Toggle screen share
 await convaiClient.screenShareControls.toggleScreenShare();
 
-// Check state
-console.log(convaiClient.isScreenShareActive);
-```
-
----
-
-## Building Custom UIs
-
-### Custom Chat Interface
-
-Use the `chatMessages` array from ConvaiClient to build your own chat UI.
-
-#### React Example
-
-```tsx
-import { useConvaiClient, AudioRenderer } from "@convai/web-sdk/react";
-import { useState } from "react";
-
-function CustomChatUI() {
-  const convaiClient = useConvaiClient({
-    apiKey: "your-api-key",
-    characterId: "your-character-id",
-  });
-
-  const { chatMessages, state } = convaiClient;
-  const [inputValue, setInputValue] = useState("");
-
-  const handleSend = () => {
-    if (inputValue.trim() && state.isConnected) {
-      convaiClient.sendUserTextMessage(inputValue);
-      setInputValue("");
-    }
-  };
-
-  return (
-    <div>
-      {/* CRITICAL: AudioRenderer for bot voice */}
-      <AudioRenderer />
-
-      {/* Chat Messages */}
-      <div className="chat-container">
-        {chatMessages.map((msg) => {
-          const isUser = msg.type.includes("user");
-          const displayMessage =
-            msg.type === "user-llm-text" || msg.type === "bot-llm-text";
-
-          if (!displayMessage) return null;
-
-          return (
-            <div
-              key={msg.id}
-              className={isUser ? "user-message" : "bot-message"}
-            >
-              <span className="sender">{isUser ? "You" : "Character"}</span>
-              <p>{msg.content}</p>
-              <span className="timestamp">
-                {new Date(msg.timestamp).toLocaleTimeString()}
-              </span>
-            </div>
-          );
-        })}
-      </div>
-
-      {/* Input */}
-      <div className="input-container">
-        <input
-          type="text"
-          value={inputValue}
-          onChange={(e) => setInputValue(e.target.value)}
-          onKeyPress={(e) => e.key === "Enter" && handleSend()}
-          placeholder="Type a message..."
-          disabled={!state.isConnected}
-        />
-        <button onClick={handleSend} disabled={!state.isConnected}>
-          Send
-        </button>
-      </div>
-
-      {/* Status Indicator */}
-      <div className="status">
-        {state.isConnecting && "Connecting..."}
-        {state.isConnected && state.agentState}
-        {!state.isConnected && "Disconnected"}
-      </div>
-    </div>
-  );
-}
+// Check screen share state
+const isActive = convaiClient.screenShareControls.isScreenShareActive;
 ```
 
-#### Vanilla Example
+**Video State Monitoring:**
 
 ```typescript
-import { ConvaiClient, AudioRenderer } from "@convai/web-sdk/vanilla";
+// React
+const { isVideoEnabled } = convaiClient;
 
-const client = new ConvaiClient({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
+// Core API (event-based)
+convaiClient.videoControls.on("videoStateChange", (state) => {
+  console.log("Video enabled:", state.isVideoEnabled);
+  console.log("Video hidden:", state.isVideoHidden);
 });
+```
 
-await client.connect();
+### Interruption
 
-// CRITICAL: Create AudioRenderer for bot voice
-const audioRenderer = new AudioRenderer(client.room);
+Interrupt the character's current response to allow the user to speak immediately.
 
-const chatContainer = document.getElementById("chat-container");
-const inputElement = document.getElementById("message-input");
-const sendButton = document.getElementById("send-button");
+**React:**
 
-// Render messages
-client.on("messagesChange", (messages) => {
-  chatContainer.innerHTML = "";
+```tsx
+function ChatInterface() {
+  const convaiClient = useConvaiClient({
+    /* config */
+  });
 
-  messages.forEach((msg) => {
-    const isUser = msg.type.includes("user");
-    const displayMessage =
-      msg.type === "user-llm-text" || msg.type === "bot-llm-text";
+  const handleInterrupt = () => {
+    // Interrupt the bot's current response
+    convaiClient.sendInterruptMessage();
+  };
 
-    if (!displayMessage) return;
+  return <button onClick={handleInterrupt}>Interrupt</button>;
+}
+```
 
-    const messageDiv = document.createElement("div");
-    messageDiv.className = isUser ? "user-message" : "bot-message";
+**Vanilla:**
 
-    const sender = document.createElement("span");
-    sender.textContent = isUser ? "You" : "Character";
-    sender.className = "sender";
+```typescript
+const interruptButton = document.getElementById("interrupt-btn");
 
-    const content = document.createElement("p");
-    content.textContent = msg.content;
+interruptButton.addEventListener("click", () => {
+  client.sendInterruptMessage();
+});
+```
 
-    const timestamp = document.createElement("span");
-    timestamp.textContent = new Date(msg.timestamp).toLocaleTimeString();
-    timestamp.className = "timestamp";
+**Voice Mode Interruption Pattern:**
 
-    messageDiv.appendChild(sender);
-    messageDiv.appendChild(content);
-    messageDiv.appendChild(timestamp);
-    chatContainer.appendChild(messageDiv);
-  });
+When implementing voice mode, interrupt the bot when the user starts speaking:
 
-  // Auto-scroll
-  chatContainer.scrollTop = chatContainer.scrollHeight;
-});
+```typescript
+// When user enters voice mode
+const enterVoiceMode = async () => {
+  // Interrupt any ongoing bot response
+  convaiClient.sendInterruptMessage();
 
-// Send message
-sendButton.addEventListener("click", () => {
-  const text = inputElement.value.trim();
-  if (text && client.state.isConnected) {
-    client.sendUserTextMessage(text);
-    inputElement.value = "";
-  }
-});
+  // Unmute microphone
+  await convaiClient.audioControls.unmuteAudio();
+};
 
-inputElement.addEventListener("keypress", (e) => {
-  if (e.key === "Enter") {
-    sendButton.click();
-  }
-});
+// When user exits voice mode
+const exitVoiceMode = async () => {
+  // Interrupt any ongoing bot response
+  convaiClient.sendInterruptMessage();
 
-// Cleanup
-// audioRenderer.destroy();
-// await client.disconnect();
+  // Mute microphone
+  await convaiClient.audioControls.muteAudio();
+};
 ```
 
----
-
-### Audio Visualizer
+### User Microphone Mute/Unmute
 
-Create real-time audio visualizers using the WebRTC room's audio tracks.
+Control the user's microphone input.
 
-#### React Example
+**React:**
 
 ```tsx
-import { useConvaiClient } from "@convai/web-sdk/react";
-import { useEffect, useRef, useState } from "react";
-
-function AudioVisualizer() {
+function AudioControls() {
   const convaiClient = useConvaiClient({
-    apiKey: "your-api-key",
-    characterId: "your-character-id",
+    /* config */
   });
 
-  const canvasRef = useRef<HTMLCanvasElement>(null);
-  const [audioLevel, setAudioLevel] = useState(0);
-
-  useEffect(() => {
-    if (!convaiClient.room) return;
-
-    let animationId: number;
-    let analyzer: AnalyserNode | null = null;
-    let dataArray: Uint8Array | null = null;
-
-    const setupAnalyzer = async () => {
-      const audioContext = new AudioContext();
-
-      // Get remote participant (bot)
-      const remoteParticipants = Array.from(
-        convaiClient.room.remoteParticipants.values(),
-      );
-
-      if (remoteParticipants.length === 0) return;
+  const handleMute = async () => {
+    await convaiClient.audioControls.muteAudio();
+  };
 
-      const participant = remoteParticipants[0];
-      const audioTracks = Array.from(
-        participant.audioTrackPublications.values(),
-      );
+  const handleUnmute = async () => {
+    await convaiClient.audioControls.unmuteAudio();
+  };
 
-      if (audioTracks.length === 0) return;
+  const handleToggle = async () => {
+    await convaiClient.audioControls.toggleAudio();
+  };
 
-      const audioTrack = audioTracks[0].track;
-      if (!audioTrack) return;
+  return (
+    <div>
+      <button onClick={handleMute}>Mute</button>
+      <button onClick={handleUnmute}>Unmute</button>
+      <button onClick={handleToggle}>Toggle</button>
+      <p>Muted: {convaiClient.audioControls.isAudioMuted ? "Yes" : "No"}</p>
+    </div>
+  );
+}
+```
 
-      // Get MediaStream from track
-      const mediaStream = new MediaStream([audioTrack.mediaStreamTrack]);
+**Vanilla:**
 
-      // Create analyzer
-      const source = audioContext.createMediaStreamSource(mediaStream);
-      analyzer = audioContext.createAnalyser();
-      analyzer.fftSize = 256;
+```typescript
+// Mute microphone
+await client.audioControls.muteAudio();
 
-      source.connect(analyzer);
-      dataArray = new Uint8Array(analyzer.frequencyBinCount);
+// Unmute microphone
+await client.audioControls.unmuteAudio();
 
-      // Animate
-      const animate = () => {
-        if (!analyzer || !dataArray) return;
+// Toggle mute state
+await client.audioControls.toggleAudio();
 
-        analyzer.getByteFrequencyData(dataArray);
+// Check mute state
+const isMuted = client.audioControls.isAudioMuted;
 
-        // Calculate average volume
-        const sum = dataArray.reduce((a, b) => a + b, 0);
-        const average = sum / dataArray.length;
-        const normalizedLevel = average / 255;
+// Enable audio (request permissions if needed)
+await client.audioControls.enableAudio();
 
-        setAudioLevel(normalizedLevel);
+// Disable audio
+await client.audioControls.disableAudio();
+```
 
-        // Draw visualization
-        drawVisualizer(dataArray);
+**Audio Device Management:**
 
-        animationId = requestAnimationFrame(animate);
-      };
+```typescript
+// Get available audio devices
+const devices = await convaiClient.audioControls.getAudioDevices();
 
-      animate();
-    };
+// Set specific audio device
+await convaiClient.audioControls.setAudioDevice(deviceId);
 
-    const drawVisualizer = (dataArray: Uint8Array) => {
-      const canvas = canvasRef.current;
-      if (!canvas) return;
+// Monitor audio level
+convaiClient.audioControls.startAudioLevelMonitoring();
 
-      const ctx = canvas.getContext("2d");
-      if (!ctx) return;
+convaiClient.audioControls.on("audioLevelChange", (level) => {
+  console.log("Audio level:", level);
+  // level is a number between 0 and 1
+});
 
-      const width = canvas.width;
-      const height = canvas.height;
+convaiClient.audioControls.stopAudioLevelMonitoring();
+```
 
-      ctx.clearRect(0, 0, width, height);
+**Audio State Monitoring:**
 
-      const barWidth = (width / dataArray.length) * 2.5;
-      let x = 0;
+```typescript
+// React
+const { isAudioMuted } = convaiClient;
+
+// Core API (event-based)
+convaiClient.audioControls.on("audioStateChange", (state) => {
+  console.log("Audio enabled:", state.isAudioEnabled);
+  console.log("Audio muted:", state.isAudioMuted);
+  console.log("Audio level:", state.audioLevel);
+});
+```
 
-      for (let i = 0; i < dataArray.length; i++) {
-        const barHeight = (dataArray[i] / 255) * height;
+### Character TTS Mute/Unmute
 
-        ctx.fillStyle = `rgb(${barHeight + 100}, 50, 150)`;
-        ctx.fillRect(x, height - barHeight, barWidth, barHeight);
+Control whether the character's responses are spoken aloud (text-to-speech).
 
-        x += barWidth + 1;
-      }
-    };
+**React:**
 
-    if (convaiClient.state.isConnected) {
-      setupAnalyzer();
-    }
+```tsx
+function TTSControls() {
+  const convaiClient = useConvaiClient({
+    /* config */
+  });
 
-    return () => {
-      if (animationId) cancelAnimationFrame(animationId);
-    };
-  }, [convaiClient.room, convaiClient.state.isConnected]);
+  const handleToggleTTS = (enabled: boolean) => {
+    convaiClient.toggleTts(enabled);
+  };
 
   return (
     <div>
-      <canvas
-        ref={canvasRef}
-        width={800}
-        height={200}
-        style={{ border: "1px solid #ccc" }}
-      />
-      <div>Audio Level: {(audioLevel * 100).toFixed(0)}%</div>
-      <div>Bot is {convaiClient.state.isSpeaking ? "speaking" : "silent"}</div>
+      <button onClick={() => handleToggleTTS(true)}>Enable TTS</button>
+      <button onClick={() => handleToggleTTS(false)}>Disable TTS</button>
     </div>
   );
 }
 ```
 
-#### Vanilla Example
+**Vanilla:**
 
 ```typescript
-import { ConvaiClient, AudioRenderer } from "@convai/web-sdk/vanilla";
+// Enable text-to-speech (character will speak responses)
+client.toggleTts(true);
+
+// Disable text-to-speech (character will only send text, no audio)
+client.toggleTts(false);
+```
 
+**Initial TTS Configuration:**
+
+```typescript
+// Set TTS state during connection
 const client = new ConvaiClient({
   apiKey: "your-api-key",
   characterId: "your-character-id",
+  ttsEnabled: true, // Enable TTS by default
 });
 
-await client.connect();
-
-// CRITICAL: AudioRenderer for playback
-const audioRenderer = new AudioRenderer(client.room);
-
-const canvas = document.getElementById("visualizer") as HTMLCanvasElement;
-const ctx = canvas.getContext("2d")!;
-
-let analyzer: AnalyserNode | null = null;
-let dataArray: Uint8Array | null = null;
-let animationId: number;
+// Or disable initially
+const client = new ConvaiClient({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+  ttsEnabled: false, // Disable TTS
+});
+```
 
-// Setup analyzer
-const audioContext = new AudioContext();
+### Voice Mode Implementation
 
-const remoteParticipants = Array.from(client.room.remoteParticipants.values());
-const participant = remoteParticipants[0];
-const audioTracks = Array.from(participant.audioTrackPublications.values());
-const audioTrack = audioTracks[0].track;
+Voice mode allows users to speak instead of typing. The widget automatically handles voice mode, but you can implement it manually.
 
-const mediaStream = new MediaStream([audioTrack.mediaStreamTrack]);
-const source = audioContext.createMediaStreamSource(mediaStream);
+**React - Manual Voice Mode:**
 
-analyzer = audioContext.createAnalyser();
-analyzer.fftSize = 256;
-source.connect(analyzer);
+```tsx
+import { useConvaiClient } from "@convai/web-sdk";
+import { useState, useEffect } from "react";
 
-dataArray = new Uint8Array(analyzer.frequencyBinCount);
+function CustomChatInterface() {
+  const convaiClient = useConvaiClient({
+    /* config */
+  });
+  const [isVoiceMode, setIsVoiceMode] = useState(false);
 
-// Animate
-function animate() {
-  if (!analyzer || !dataArray) return;
+  const enterVoiceMode = async () => {
+    // Interrupt any ongoing bot response
+    convaiClient.sendInterruptMessage();
 
-  analyzer.getByteFrequencyData(dataArray);
+    // Unmute microphone
+    await convaiClient.audioControls.unmuteAudio();
 
-  // Clear canvas
-  ctx.clearRect(0, 0, canvas.width, canvas.height);
+    setIsVoiceMode(true);
+  };
 
-  const barWidth = (canvas.width / dataArray.length) * 2.5;
-  let x = 0;
+  const exitVoiceMode = async () => {
+    // Interrupt any ongoing bot response
+    convaiClient.sendInterruptMessage();
 
-  for (let i = 0; i < dataArray.length; i++) {
-    const barHeight = (dataArray[i] / 255) * canvas.height;
+    // Mute microphone
+    await convaiClient.audioControls.muteAudio();
 
-    ctx.fillStyle = `rgb(${barHeight + 100}, 50, 150)`;
-    ctx.fillRect(x, canvas.height - barHeight, barWidth, barHeight);
+    setIsVoiceMode(false);
+  };
 
-    x += barWidth + 1;
-  }
+  // Monitor user transcription for voice input
+  useEffect(() => {
+    const transcription = convaiClient.userTranscription;
+    if (transcription && isVoiceMode) {
+      // Display real-time transcription
+      console.log("User is saying:", transcription);
+    }
+  }, [convaiClient.userTranscription, isVoiceMode]);
 
-  animationId = requestAnimationFrame(animate);
+  return (
+    <div>
+      {isVoiceMode ? (
+        <div>
+          <p>Listening: {convaiClient.userTranscription}</p>
+          <button onClick={exitVoiceMode}>Stop Voice Mode</button>
+        </div>
+      ) : (
+        <button onClick={enterVoiceMode}>Start Voice Mode</button>
+      )}
+    </div>
+  );
 }
-
-animate();
-
-// Cleanup
-// cancelAnimationFrame(animationId);
-// audioRenderer.destroy();
-// await client.disconnect();
-```
-
----
-
-### Message Types
-
-All messages from `convaiClient.chatMessages` have a `type` field:
-
-```typescript
-type ChatMessageType =
-  | "user" // User's sent message (raw)
-  | "user-transcription" // Real-time speech-to-text from user
-  | "user-llm-text" // User text processed by LLM (final)
-  | "convai" // Character's response (raw)
-  | "bot-llm-text" // Character's LLM-generated text (final)
-  | "bot-emotion" // Character's emotional state
-  | "emotion" // Generic emotion
-  | "behavior-tree" // Behavior tree response
-  | "action" // Action execution
-  | "interrupt-bot"; // Interrupt message
 ```
 
-**For Chat UIs, filter to:**
+**Vanilla - Manual Voice Mode:**
 
 ```typescript
-const displayMessages = chatMessages.filter(
-  (msg) => msg.type === "user-llm-text" || msg.type === "bot-llm-text",
-);
-```
+let isVoiceMode = false;
 
----
+const enterVoiceMode = async () => {
+  // Interrupt any ongoing bot response
+  client.sendInterruptMessage();
 
-## API Reference
+  // Unmute microphone
+  await client.audioControls.unmuteAudio();
 
-### Configuration
+  isVoiceMode = true;
+  updateUI();
+};
 
-```typescript
-interface ConvaiConfig {
-  /** Your Convai API key from convai.com dashboard (required) */
-  apiKey: string;
+const exitVoiceMode = async () => {
+  // Interrupt any ongoing bot response
+  client.sendInterruptMessage();
 
-  /** The Character ID to connect to (required) */
-  characterId: string;
+  // Mute microphone
+  await client.audioControls.muteAudio();
 
-  /**
-   * End user identifier for speaker management (optional).
-   * When provided: enables long-term memory and analytics
-   * When not provided: anonymous mode, no persistent memory
-   */
-  endUserId?: string;
+  isVoiceMode = false;
+  updateUI();
+};
 
-  /** Custom Convai API URL (optional) */
-  url?: string;
+// Monitor user transcription
+client.on("userTranscriptionChange", (transcription) => {
+  if (isVoiceMode && transcription) {
+    // Display real-time transcription
+    document.getElementById("transcription").textContent = transcription;
+  }
+});
 
-  /**
-   * Enable video capability (default: false).
-   * If true, connection_type will be "video" (supports audio, video, screenshare).
-   * If false, connection_type will be "audio" (audio only).
-   * ⚠️ REQUIRED for video and screen share features.
-   */
-  enableVideo?: boolean;
+function updateUI() {
+  const voiceButton = document.getElementById("voice-btn");
+  const transcriptionDiv = document.getElementById("transcription");
 
-  /**
-   * Start with video camera on when connecting (default: false).
-   * Only works if enableVideo is true.
-   */
-  startWithVideoOn?: boolean;
+  if (isVoiceMode) {
+    voiceButton.textContent = "Stop Voice Mode";
+    transcriptionDiv.style.display = "block";
+  } else {
+    voiceButton.textContent = "Start Voice Mode";
+    transcriptionDiv.style.display = "none";
+  }
+}
+```
 
-  /**
-   * Start with microphone on when connecting (default: false).
-   * If false, microphone stays off until user enables it.
-   */
-  startWithAudioOn?: boolean;
+**Voice Mode with State Monitoring:**
 
-  /**
-   * Enable text-to-speech audio generation (default: true).
-   */
-  ttsEnabled?: boolean;
-}
+```typescript
+// Monitor agent state to handle voice mode transitions
+convaiClient.on("stateChange", (state) => {
+  if (isVoiceMode) {
+    switch (state.agentState) {
+      case "listening":
+        // User can speak
+        console.log("Bot is listening");
+        break;
+      case "thinking":
+        // Bot is processing
+        console.log("Bot is thinking");
+        break;
+      case "speaking":
+        // Bot is responding
+        console.log("Bot is speaking");
+        // Optionally interrupt if user wants to speak
+        break;
+    }
+  }
+});
 ```
 
 ### Connection Management
 
+**Connect:**
+
 ```typescript
-// Connect
+// React - config passed to hook
+const convaiClient = useConvaiClient({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+});
+
+// Or connect manually
 await convaiClient.connect({
   apiKey: "your-api-key",
   characterId: "your-character-id",
-  enableVideo: true,
 });
 
-// Disconnect
+// Vanilla
+const client = new ConvaiClient();
+await client.connect({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+});
+```
+
+**Disconnect:**
+
+```typescript
 await convaiClient.disconnect();
+```
+
+**Reconnect:**
 
-// Reconnect
+```typescript
 await convaiClient.reconnect();
+```
 
-// Reset session (clear conversation history)
+**Reset Session:**
+
+```typescript
+// Clear conversation history and start new session
 convaiClient.resetSession();
+```
+
+**Connection State:**
+
+```typescript
+// React
+const { state } = convaiClient;
+console.log("Connected:", state.isConnected);
+console.log("Connecting:", state.isConnecting);
+console.log("Agent state:", state.agentState); // 'disconnected' | 'connected' | 'listening' | 'thinking' | 'speaking'
+
+// Core API (event-based)
+convaiClient.on("stateChange", (state) => {
+  console.log("State changed:", state);
+});
+
+convaiClient.on("connect", () => {
+  console.log("Connected");
+});
 
-// Check connection state
-console.log(convaiClient.state.isConnected);
-console.log(convaiClient.state.isConnecting);
-console.log(convaiClient.state.agentState); // 'disconnected' | 'connected' | 'listening' | 'thinking' | 'speaking'
-console.log(convaiClient.isBotReady); // Bot ready to receive messages
+convaiClient.on("disconnect", () => {
+  console.log("Disconnected");
+});
 ```
 
 ### Messaging
 
+**Send Text Message:**
+
 ```typescript
-// Send text message
 convaiClient.sendUserTextMessage("Hello, how are you?");
+```
 
-// Send trigger message (invoke character action)
+**Send Trigger Message:**
+
+```typescript
+// Trigger specific character action
 convaiClient.sendTriggerMessage("greet", "User entered the room");
 
-// Interrupt character's current response
-convaiClient.sendInterruptMessage();
+// Trigger without message
+convaiClient.sendTriggerMessage("wave");
+```
 
-// Update context
-convaiClient.updateTemplateKeys({ user_name: "John" });
-convaiClient.updateDynamicInfo({ text: "User is browsing products" });
+**Update Context:**
 
-// Access messages
-console.log(convaiClient.chatMessages);
+```typescript
+// Update template keys (e.g., user name, location)
+convaiClient.updateTemplateKeys({
+  user_name: "John",
+  location: "New York",
+});
 
-// Access real-time user transcription
-console.log(convaiClient.userTranscription);
+// Update dynamic information
+convaiClient.updateDynamicInfo({
+  text: "User is currently browsing the products page",
+});
 ```
 
-### Audio Controls
+**Message History:**
 
 ```typescript
-// Mute/unmute microphone
-await convaiClient.audioControls.muteAudio();
-await convaiClient.audioControls.unmuteAudio();
-await convaiClient.audioControls.toggleAudio();
+// React
+const { chatMessages } = convaiClient;
 
-// Check mute state (two equivalent ways)
-console.log(convaiClient.isAudioMuted); // convenience property
-console.log(convaiClient.audioControls.isAudioMuted); // via controls
+// Core API (event-based)
+convaiClient.on("message", (message: ChatMessage) => {
+  console.log("New message:", message.content);
+  console.log("Message type:", message.type);
+});
 
-// Get available microphones
-const devices = await convaiClient.audioControls.getAudioDevices();
+convaiClient.on("messagesChange", (messages: ChatMessage[]) => {
+  console.log("All messages:", messages);
+});
+```
 
-// Set microphone
-await convaiClient.audioControls.setAudioDevice(deviceId);
+**Message Types:**
 
-// Monitor audio level
-convaiClient.audioControls.startAudioLevelMonitoring();
-convaiClient.audioControls.on("audioLevelChange", (level) => {
-  console.log("Audio level:", level); // 0 to 1
-});
-convaiClient.audioControls.stopAudioLevelMonitoring();
+```typescript
+type ChatMessageType =
+  | "user" // User's sent message
+  | "convai" // Character's response
+  | "user-transcription" // Real-time speech-to-text from user
+  | "bot-llm-text" // Character's LLM-generated text
+  | "emotion" // Character's emotional state
+  | "behavior-tree" // Behavior tree response
+  | "action" // Action execution
+  | "bot-emotion" // Bot emotional response
+  | "user-llm-text" // User text processed by LLM
+  | "interrupt-bot"; // Interrupt message
 ```
 
-### Video Controls
+### State Monitoring
 
-**⚠️ Requires `enableVideo: true` in config.**
+**Agent State:**
 
 ```typescript
-// Enable/disable camera
-await convaiClient.videoControls.enableVideo();
-await convaiClient.videoControls.disableVideo();
-await convaiClient.videoControls.toggleVideo();
+// React
+const { state } = convaiClient;
 
-// Check video state (two equivalent ways)
-console.log(convaiClient.isVideoEnabled); // convenience property
-console.log(convaiClient.videoControls.isVideoEnabled); // via controls
+// Check specific states
+if (state.isListening) {
+  console.log("Bot is listening");
+}
 
-// Set video quality
-await convaiClient.videoControls.setVideoQuality("high"); // 'low' | 'medium' | 'high'
+if (state.isThinking) {
+  console.log("Bot is thinking");
+}
 
-// Get available cameras
-const devices = await convaiClient.videoControls.getVideoDevices();
+if (state.isSpeaking) {
+  console.log("Bot is speaking");
+}
 
-// Switch camera
-await convaiClient.videoControls.setVideoDevice(deviceId);
+// Combined state
+console.log(state.agentState); // 'disconnected' | 'connected' | 'listening' | 'thinking' | 'speaking'
 ```
 
-### Screen Share Controls
-
-**⚠️ Requires `enableVideo: true` in config.**
+**User Transcription:**
 
 ```typescript
-// Start/stop screen share
-await convaiClient.screenShareControls.enableScreenShare();
-await convaiClient.screenShareControls.enableScreenShareWithAudio();
-await convaiClient.screenShareControls.disableScreenShare();
-await convaiClient.screenShareControls.toggleScreenShare();
+// React
+const { userTranscription } = convaiClient;
 
-// Check screen share state (two equivalent ways)
-console.log(convaiClient.isScreenShareActive); // convenience property
-console.log(convaiClient.screenShareControls.isScreenShareActive); // via controls
+// Core API (event-based)
+convaiClient.on("userTranscriptionChange", (transcription: string) => {
+  console.log("User is saying:", transcription);
+});
 ```
 
----
+**Bot Ready State:**
+
+```typescript
+// React
+const { isBotReady } = convaiClient;
+
+// Core API (event-based)
+convaiClient.on("botReady", () => {
+  console.log("Bot is ready to receive messages");
+});
+```
 
-## Getting Credentials
+## Getting Convai Credentials
 
 1. Visit [convai.com](https://convai.com) and create an account
 2. Navigate to your dashboard
@@ -1328,71 +816,41 @@ console.log(convaiClient.screenShareControls.isScreenShareActive); // via contro
 4. Copy your **API Key** from the dashboard
 5. Copy your **Character ID** from the character details
 
----
-
-## TypeScript Support
-
-All exports are fully typed:
-
-**React:**
+## Import Paths
 
 ```typescript
-import type {
-  // Configuration
-  ConvaiConfig,
+// Default: React version (backward compatible)
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
 
-  // State
-  ConvaiClientState,
-
-  // Messages
-  ChatMessage,
-  ChatMessageType,
+// Explicit React import
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
 
-  // Client
-  IConvaiClient,
-  ConvaiClient,
+// Vanilla JS/TS
+import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
 
-  // Controls
-  AudioControls,
-  VideoControls,
-  ScreenShareControls,
-} from "@convai/web-sdk/react";
+// Core only (no UI, framework agnostic)
+import { ConvaiClient } from "@convai/web-sdk/core";
 ```
 
-**Vanilla:**
+## TypeScript Support
+
+All exports are fully typed:
 
 ```typescript
 import type {
-  // Configuration
+  ConvaiClient,
   ConvaiConfig,
-
-  // State
   ConvaiClientState,
-
-  // Messages
   ChatMessage,
-  ChatMessageType,
-
-  // Client
-  IConvaiClient,
-  ConvaiClient,
-
-  // Controls
   AudioControls,
   VideoControls,
   ScreenShareControls,
-
-  // Widget
-  VanillaWidget,
-  VanillaWidgetOptions,
-} from "@convai/web-sdk/vanilla";
+  IConvaiClient,
+} from "@convai/web-sdk";
 ```
 
----
-
 ## Support
 
-- **Documentation**: [API Reference](./API_REFERENCE.md)
-- **Forum**: [Convai Forum](https://forum.convai.com)
-- **Website**: [convai.com](https://convai.com)
-- **Issues**: [GitHub Issues](https://github.com/convai/web-sdk/issues)
+- [Convai Forum](https://forum.convai.com)
+- [API Reference](./API_REFERENCE.md)
+- [Convai Website](https://convai.com)