@convai/web-sdk 0.2.3-beta.1 → 0.2.4

package/README.md

@@ -1,6 +1,47 @@
 # @convai/web-sdk
 
-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.
+[![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)
+
+---
 
 ## Installation
 
@@ -8,14 +49,25 @@ JavaScript/TypeScript SDK for Convai AI voice assistants. Build voice-powered AI
 npm install @convai/web-sdk
 ```
 
-## Basic Setup
+**Peer Dependencies (React only):**
 
-### React
+```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.
 
 ```tsx
-import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
 
 function App() {
+  // Initialize the Convai client
   const convaiClient = useConvaiClient({
     apiKey: "your-api-key",
     characterId: "your-character-id",
@@ -25,7 +77,166 @@ function App() {
 }
 ```
 
-### Vanilla TypeScript
+**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
 
 ```typescript
 import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
@@ -36,7 +247,7 @@ const client = new ConvaiClient({
   characterId: "your-character-id",
 });
 
-// Create widget - auto-connects on first user click
+// Create and mount widget - auto-connects on first user click
 const widget = createConvaiWidget(document.body, {
   convaiClient: client,
 });
@@ -45,770 +256,1025 @@ 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.
 
-- `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
+**When to Use**: Every React app using Convai needs this hook.
 
-**Components:**
+**What It Does**:
 
-- `AudioRenderer` - Audio playback component
-- `AudioContext` - Audio context provider
+- 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
+  });
+
+  // Access reactive state
+  const { state, chatMessages, userTranscription, isBotReady } = convaiClient;
+
+  // Use controls
+  const handleMute = () => convaiClient.audioControls.muteAudio();
+  const handleSend = () =>
+    convaiClient.sendUserTextMessage("Hello, character!");
+
+  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.
 
-### ConvaiWidget Props (React)
+**How It Works**: React Context that holds the active WebRTC room.
 
 ```tsx
-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;
+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>;
 }
 ```
 
-### createConvaiWidget Options (Vanilla)
+### 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
-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;
-}
+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();
 ```
 
-### ConvaiConfig
+### 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
-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;
-}
+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();
 ```
 
-## Features
+### Vanilla Exports Reference
 
-### Video Enabled Chat
+```typescript
+// Widget
+import { createConvaiWidget, destroyConvaiWidget } from "@convai/web-sdk/vanilla";
 
-To enable video capabilities, set `enableVideo: true` in your configuration. This enables audio, video, and screen sharing.
+// Core Client
+import { ConvaiClient } from "@convai/web-sdk/vanilla";
 
-**React:**
+// Audio Rendering (Critical)
+import { AudioRenderer } from "@convai/web-sdk/vanilla";
+
+// Types
+import type {
+  VanillaWidget,
+  VanillaWidgetOptions,
+  ConvaiConfig,
+  ConvaiClientState,
+  ChatMessage,
+  IConvaiClient,
+} from "@convai/web-sdk/vanilla";
+```
+
+---
+
+## 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.
+
+**Without both, video features will NOT work.**
+
+---
+
+### Enabling Video
+
+#### React
 
 ```tsx
-import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
 
 function App() {
+  // ✅ STEP 1: Enable video in client config
   const convaiClient = useConvaiClient({
     apiKey: "your-api-key",
     characterId: "your-character-id",
-    enableVideo: true,
+    enableVideo: true, // ← REQUIRED for video
     startWithVideoOn: false, // Camera off by default
   });
 
   return (
     <ConvaiWidget
       convaiClient={convaiClient}
-      showVideo={true}
-      showScreenShare={true}
+      showVideo={true} // ← STEP 2: Show video controls
+      showScreenShare={false} // Optional: hide screen share
     />
   );
 }
 ```
 
-**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,
+  enableVideo: true, // ← REQUIRED for video
   startWithVideoOn: false,
 });
 
 const widget = createConvaiWidget(document.body, {
   convaiClient: client,
-  showVideo: true,
-  showScreenShare: true,
+  showVideo: true, // ← STEP 2: Show video controls
+  showScreenShare: false,
 });
 ```
 
-**Manual Video Controls:**
+#### Manual Video Control
 
 ```typescript
-// Enable video camera
+// Enable camera
 await convaiClient.videoControls.enableVideo();
 
-// Disable video camera
+// Disable camera
 await convaiClient.videoControls.disableVideo();
 
-// Toggle video
+// Toggle camera
 await convaiClient.videoControls.toggleVideo();
 
-// Check video state
-const isVideoEnabled = convaiClient.videoControls.isVideoEnabled;
+// Check state
+console.log(convaiClient.isVideoEnabled);
 
 // Set video quality
 await convaiClient.videoControls.setVideoQuality("high"); // 'low' | 'medium' | 'high'
 
-// Get available video devices
+// Get available cameras
 const devices = await convaiClient.videoControls.getVideoDevices();
 
-// Set specific video device
+// Switch camera
 await convaiClient.videoControls.setVideoDevice(deviceId);
 ```
 
-**Screen Sharing:**
-
-```typescript
-// Enable screen share
-await convaiClient.screenShareControls.enableScreenShare();
-
-// Enable screen share with audio
-await convaiClient.screenShareControls.enableScreenShareWithAudio();
-
-// Disable screen share
-await convaiClient.screenShareControls.disableScreenShare();
-
-// Toggle screen share
-await convaiClient.screenShareControls.toggleScreenShare();
-
-// Check screen share state
-const isActive = convaiClient.screenShareControls.isScreenShareActive;
-```
-
-**Video State Monitoring:**
-
-```typescript
-// React
-const { isVideoEnabled } = convaiClient;
-
-// Core API (event-based)
-convaiClient.videoControls.on("videoStateChange", (state) => {
-  console.log("Video enabled:", state.isVideoEnabled);
-  console.log("Video hidden:", state.isVideoHidden);
-});
-```
+---
 
-### Interruption
+### Enabling Screen Share
 
-Interrupt the character's current response to allow the user to speak immediately.
+Screen sharing **requires** `enableVideo: true` (connection type must be `"video"`).
 
-**React:**
+#### React
 
 ```tsx
-function ChatInterface() {
+import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
+
+function App() {
+  // ✅ STEP 1: Enable video (required for screen share)
   const convaiClient = useConvaiClient({
-    /* config */
+    apiKey: "your-api-key",
+    characterId: "your-character-id",
+    enableVideo: true, // ← REQUIRED for screen share
   });
 
-  const handleInterrupt = () => {
-    // Interrupt the bot's current response
-    convaiClient.sendInterruptMessage();
-  };
-
-  return <button onClick={handleInterrupt}>Interrupt</button>;
+  return (
+    <ConvaiWidget
+      convaiClient={convaiClient}
+      showVideo={true} // Optional: show video controls
+      showScreenShare={true} // ← STEP 2: Show screen share controls
+    />
+  );
 }
 ```
 
-**Vanilla:**
+#### Vanilla
 
 ```typescript
-const interruptButton = document.getElementById("interrupt-btn");
+import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
 
-interruptButton.addEventListener("click", () => {
-  client.sendInterruptMessage();
+// ✅ 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
 });
-```
 
-**Voice Mode Interruption Pattern:**
+const widget = createConvaiWidget(document.body, {
+  convaiClient: client,
+  showVideo: true,
+  showScreenShare: true, // ← STEP 2: Show screen share controls
+});
+```
 
-When implementing voice mode, interrupt the bot when the user starts speaking:
+#### Manual Screen Share Control
 
 ```typescript
-// When user enters voice mode
-const enterVoiceMode = async () => {
-  // Interrupt any ongoing bot response
-  convaiClient.sendInterruptMessage();
+// Start screen share
+await convaiClient.screenShareControls.enableScreenShare();
+
+// Start screen share with audio
+await convaiClient.screenShareControls.enableScreenShareWithAudio();
 
-  // Unmute microphone
-  await convaiClient.audioControls.unmuteAudio();
-};
+// Stop screen share
+await convaiClient.screenShareControls.disableScreenShare();
 
-// When user exits voice mode
-const exitVoiceMode = async () => {
-  // Interrupt any ongoing bot response
-  convaiClient.sendInterruptMessage();
+// Toggle screen share
+await convaiClient.screenShareControls.toggleScreenShare();
 
-  // Mute microphone
-  await convaiClient.audioControls.muteAudio();
-};
+// Check state
+console.log(convaiClient.isScreenShareActive);
 ```
 
-### User Microphone Mute/Unmute
+---
+
+## Building Custom UIs
+
+### Custom Chat Interface
 
-Control the user's microphone input.
+Use the `chatMessages` array from ConvaiClient to build your own chat UI.
 
-**React:**
+#### React Example
 
 ```tsx
-function AudioControls() {
+import { useConvaiClient, AudioRenderer } from "@convai/web-sdk/react";
+import { useState } from "react";
+
+function CustomChatUI() {
   const convaiClient = useConvaiClient({
-    /* config */
+    apiKey: "your-api-key",
+    characterId: "your-character-id",
   });
 
-  const handleMute = async () => {
-    await convaiClient.audioControls.muteAudio();
-  };
-
-  const handleUnmute = async () => {
-    await convaiClient.audioControls.unmuteAudio();
-  };
+  const { chatMessages, state } = convaiClient;
+  const [inputValue, setInputValue] = useState("");
 
-  const handleToggle = async () => {
-    await convaiClient.audioControls.toggleAudio();
+  const handleSend = () => {
+    if (inputValue.trim() && state.isConnected) {
+      convaiClient.sendUserTextMessage(inputValue);
+      setInputValue("");
+    }
   };
 
   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>
+      {/* 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>
   );
 }
 ```
 
-**Vanilla:**
+#### Vanilla Example
 
 ```typescript
-// Mute microphone
-await client.audioControls.muteAudio();
+import { ConvaiClient, AudioRenderer } from "@convai/web-sdk/vanilla";
 
-// Unmute microphone
-await client.audioControls.unmuteAudio();
+const client = new ConvaiClient({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+});
 
-// Toggle mute state
-await client.audioControls.toggleAudio();
+await client.connect();
 
-// Check mute state
-const isMuted = client.audioControls.isAudioMuted;
+// CRITICAL: Create AudioRenderer for bot voice
+const audioRenderer = new AudioRenderer(client.room);
 
-// Enable audio (request permissions if needed)
-await client.audioControls.enableAudio();
+const chatContainer = document.getElementById("chat-container");
+const inputElement = document.getElementById("message-input");
+const sendButton = document.getElementById("send-button");
 
-// Disable audio
-await client.audioControls.disableAudio();
-```
+// Render messages
+client.on("messagesChange", (messages) => {
+  chatContainer.innerHTML = "";
 
-**Audio Device Management:**
+  messages.forEach((msg) => {
+    const isUser = msg.type.includes("user");
+    const displayMessage =
+      msg.type === "user-llm-text" || msg.type === "bot-llm-text";
 
-```typescript
-// Get available audio devices
-const devices = await convaiClient.audioControls.getAudioDevices();
+    if (!displayMessage) return;
 
-// Set specific audio device
-await convaiClient.audioControls.setAudioDevice(deviceId);
+    const messageDiv = document.createElement("div");
+    messageDiv.className = isUser ? "user-message" : "bot-message";
 
-// Monitor audio level
-convaiClient.audioControls.startAudioLevelMonitoring();
+    const sender = document.createElement("span");
+    sender.textContent = isUser ? "You" : "Character";
+    sender.className = "sender";
 
-convaiClient.audioControls.on("audioLevelChange", (level) => {
-  console.log("Audio level:", level);
-  // level is a number between 0 and 1
-});
+    const content = document.createElement("p");
+    content.textContent = msg.content;
 
-convaiClient.audioControls.stopAudioLevelMonitoring();
-```
+    const timestamp = document.createElement("span");
+    timestamp.textContent = new Date(msg.timestamp).toLocaleTimeString();
+    timestamp.className = "timestamp";
 
-**Audio State Monitoring:**
+    messageDiv.appendChild(sender);
+    messageDiv.appendChild(content);
+    messageDiv.appendChild(timestamp);
+    chatContainer.appendChild(messageDiv);
+  });
 
-```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);
+  // Auto-scroll
+  chatContainer.scrollTop = chatContainer.scrollHeight;
+});
+
+// Send message
+sendButton.addEventListener("click", () => {
+  const text = inputElement.value.trim();
+  if (text && client.state.isConnected) {
+    client.sendUserTextMessage(text);
+    inputElement.value = "";
+  }
+});
+
+inputElement.addEventListener("keypress", (e) => {
+  if (e.key === "Enter") {
+    sendButton.click();
+  }
 });
+
+// Cleanup
+// audioRenderer.destroy();
+// await client.disconnect();
 ```
 
-### Character TTS Mute/Unmute
+---
 
-Control whether the character's responses are spoken aloud (text-to-speech).
+### Audio Visualizer
 
-**React:**
+Create real-time audio visualizers using the WebRTC room's audio tracks.
+
+#### React Example
 
 ```tsx
-function TTSControls() {
+import { useConvaiClient } from "@convai/web-sdk/react";
+import { useEffect, useRef, useState } from "react";
+
+function AudioVisualizer() {
   const convaiClient = useConvaiClient({
-    /* config */
+    apiKey: "your-api-key",
+    characterId: "your-character-id",
   });
 
-  const handleToggleTTS = (enabled: boolean) => {
-    convaiClient.toggleTts(enabled);
-  };
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const [audioLevel, setAudioLevel] = useState(0);
 
-  return (
-    <div>
-      <button onClick={() => handleToggleTTS(true)}>Enable TTS</button>
-      <button onClick={() => handleToggleTTS(false)}>Disable TTS</button>
-    </div>
-  );
-}
-```
+  useEffect(() => {
+    if (!convaiClient.room) return;
 
-**Vanilla:**
+    let animationId: number;
+    let analyzer: AnalyserNode | null = null;
+    let dataArray: Uint8Array | null = null;
 
-```typescript
-// Enable text-to-speech (character will speak responses)
-client.toggleTts(true);
+    const setupAnalyzer = async () => {
+      const audioContext = new AudioContext();
 
-// Disable text-to-speech (character will only send text, no audio)
-client.toggleTts(false);
-```
+      // Get remote participant (bot)
+      const remoteParticipants = Array.from(
+        convaiClient.room.remoteParticipants.values()
+      );
 
-**Initial TTS Configuration:**
+      if (remoteParticipants.length === 0) return;
 
-```typescript
-// Set TTS state during connection
-const client = new ConvaiClient({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
-  ttsEnabled: true, // Enable TTS by default
-});
+      const participant = remoteParticipants[0];
+      const audioTracks = Array.from(
+        participant.audioTrackPublications.values()
+      );
 
-// Or disable initially
-const client = new ConvaiClient({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
-  ttsEnabled: false, // Disable TTS
-});
-```
+      if (audioTracks.length === 0) return;
 
-### Voice Mode Implementation
+      const audioTrack = audioTracks[0].track;
+      if (!audioTrack) return;
 
-Voice mode allows users to speak instead of typing. The widget automatically handles voice mode, but you can implement it manually.
+      // Get MediaStream from track
+      const mediaStream = new MediaStream([audioTrack.mediaStreamTrack]);
 
-**React - Manual Voice Mode:**
+      // Create analyzer
+      const source = audioContext.createMediaStreamSource(mediaStream);
+      analyzer = audioContext.createAnalyser();
+      analyzer.fftSize = 256;
 
-```tsx
-import { useConvaiClient } from "@convai/web-sdk";
-import { useState, useEffect } from "react";
+      source.connect(analyzer);
+      dataArray = new Uint8Array(analyzer.frequencyBinCount);
 
-function CustomChatInterface() {
-  const convaiClient = useConvaiClient({
-    /* config */
-  });
-  const [isVoiceMode, setIsVoiceMode] = useState(false);
+      // Animate
+      const animate = () => {
+        if (!analyzer || !dataArray) return;
 
-  const enterVoiceMode = async () => {
-    // Interrupt any ongoing bot response
-    convaiClient.sendInterruptMessage();
+        analyzer.getByteFrequencyData(dataArray);
 
-    // Unmute microphone
-    await convaiClient.audioControls.unmuteAudio();
+        // Calculate average volume
+        const sum = dataArray.reduce((a, b) => a + b, 0);
+        const average = sum / dataArray.length;
+        const normalizedLevel = average / 255;
 
-    setIsVoiceMode(true);
-  };
+        setAudioLevel(normalizedLevel);
 
-  const exitVoiceMode = async () => {
-    // Interrupt any ongoing bot response
-    convaiClient.sendInterruptMessage();
+        // Draw visualization
+        drawVisualizer(dataArray);
 
-    // Mute microphone
-    await convaiClient.audioControls.muteAudio();
+        animationId = requestAnimationFrame(animate);
+      };
 
-    setIsVoiceMode(false);
-  };
+      animate();
+    };
 
-  // Monitor user transcription for voice input
-  useEffect(() => {
-    const transcription = convaiClient.userTranscription;
-    if (transcription && isVoiceMode) {
-      // Display real-time transcription
-      console.log("User is saying:", transcription);
+    const drawVisualizer = (dataArray: Uint8Array) => {
+      const canvas = canvasRef.current;
+      if (!canvas) return;
+
+      const ctx = canvas.getContext("2d");
+      if (!ctx) return;
+
+      const width = canvas.width;
+      const height = canvas.height;
+
+      ctx.clearRect(0, 0, width, height);
+
+      const barWidth = (width / dataArray.length) * 2.5;
+      let x = 0;
+
+      for (let i = 0; i < dataArray.length; i++) {
+        const barHeight = (dataArray[i] / 255) * height;
+
+        ctx.fillStyle = `rgb(${barHeight + 100}, 50, 150)`;
+        ctx.fillRect(x, height - barHeight, barWidth, barHeight);
+
+        x += barWidth + 1;
+      }
+    };
+
+    if (convaiClient.state.isConnected) {
+      setupAnalyzer();
     }
-  }, [convaiClient.userTranscription, isVoiceMode]);
+
+    return () => {
+      if (animationId) cancelAnimationFrame(animationId);
+    };
+  }, [convaiClient.room, convaiClient.state.isConnected]);
 
   return (
     <div>
-      {isVoiceMode ? (
-        <div>
-          <p>Listening: {convaiClient.userTranscription}</p>
-          <button onClick={exitVoiceMode}>Stop Voice Mode</button>
-        </div>
-      ) : (
-        <button onClick={enterVoiceMode}>Start Voice Mode</button>
-      )}
+      <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>
     </div>
   );
 }
 ```
 
-**Vanilla - Manual Voice Mode:**
+#### Vanilla Example
 
 ```typescript
-let isVoiceMode = false;
+import { ConvaiClient, AudioRenderer } from "@convai/web-sdk/vanilla";
 
-const enterVoiceMode = async () => {
-  // Interrupt any ongoing bot response
-  client.sendInterruptMessage();
+const client = new ConvaiClient({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+});
 
-  // Unmute microphone
-  await client.audioControls.unmuteAudio();
+await client.connect();
 
-  isVoiceMode = true;
-  updateUI();
-};
+// CRITICAL: AudioRenderer for playback
+const audioRenderer = new AudioRenderer(client.room);
 
-const exitVoiceMode = async () => {
-  // Interrupt any ongoing bot response
-  client.sendInterruptMessage();
+const canvas = document.getElementById("visualizer") as HTMLCanvasElement;
+const ctx = canvas.getContext("2d")!;
 
-  // Mute microphone
-  await client.audioControls.muteAudio();
+let analyzer: AnalyserNode | null = null;
+let dataArray: Uint8Array | null = null;
+let animationId: number;
 
-  isVoiceMode = false;
-  updateUI();
-};
+// Setup analyzer
+const audioContext = new AudioContext();
 
-// Monitor user transcription
-client.on("userTranscriptionChange", (transcription) => {
-  if (isVoiceMode && transcription) {
-    // Display real-time transcription
-    document.getElementById("transcription").textContent = transcription;
-  }
-});
+const remoteParticipants = Array.from(client.room.remoteParticipants.values());
+const participant = remoteParticipants[0];
+const audioTracks = Array.from(participant.audioTrackPublications.values());
+const audioTrack = audioTracks[0].track;
 
-function updateUI() {
-  const voiceButton = document.getElementById("voice-btn");
-  const transcriptionDiv = document.getElementById("transcription");
+const mediaStream = new MediaStream([audioTrack.mediaStreamTrack]);
+const source = audioContext.createMediaStreamSource(mediaStream);
 
-  if (isVoiceMode) {
-    voiceButton.textContent = "Stop Voice Mode";
-    transcriptionDiv.style.display = "block";
-  } else {
-    voiceButton.textContent = "Start Voice Mode";
-    transcriptionDiv.style.display = "none";
-  }
-}
-```
+analyzer = audioContext.createAnalyser();
+analyzer.fftSize = 256;
+source.connect(analyzer);
 
-**Voice Mode with State Monitoring:**
+dataArray = new Uint8Array(analyzer.frequencyBinCount);
 
-```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;
-    }
-  }
-});
-```
+// Animate
+function animate() {
+  if (!analyzer || !dataArray) return;
 
-### Connection Management
+  analyzer.getByteFrequencyData(dataArray);
 
-**Connect:**
+  // Clear canvas
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
 
-```typescript
-// React - config passed to hook
-const convaiClient = useConvaiClient({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
-});
+  const barWidth = (canvas.width / dataArray.length) * 2.5;
+  let x = 0;
 
-// Or connect manually
-await convaiClient.connect({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
-});
+  for (let i = 0; i < dataArray.length; i++) {
+    const barHeight = (dataArray[i] / 255) * canvas.height;
 
-// Vanilla
-const client = new ConvaiClient();
-await client.connect({
-  apiKey: "your-api-key",
-  characterId: "your-character-id",
-});
+    ctx.fillStyle = `rgb(${barHeight + 100}, 50, 150)`;
+    ctx.fillRect(x, canvas.height - barHeight, barWidth, barHeight);
+
+    x += barWidth + 1;
+  }
+
+  animationId = requestAnimationFrame(animate);
+}
+
+animate();
+
+// Cleanup
+// cancelAnimationFrame(animationId);
+// audioRenderer.destroy();
+// await client.disconnect();
 ```
 
-**Disconnect:**
+---
+
+### Message Types
+
+All messages from `convaiClient.chatMessages` have a `type` field:
 
 ```typescript
-await convaiClient.disconnect();
+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
 ```
 
-**Reconnect:**
+**For Chat UIs, filter to:**
 
 ```typescript
-await convaiClient.reconnect();
+const displayMessages = chatMessages.filter(
+  (msg) => msg.type === "user-llm-text" || msg.type === "bot-llm-text"
+);
 ```
 
-**Reset Session:**
+---
+
+## API Reference
+
+### Configuration
 
 ```typescript
-// Clear conversation history and start new session
-convaiClient.resetSession();
+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) */
+  url?: string;
+
+  /**
+   * 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;
+
+  /**
+   * 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;
+}
 ```
 
-**Connection State:**
+### Connection Management
 
 ```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);
+// Connect
+await convaiClient.connect({
+  apiKey: "your-api-key",
+  characterId: "your-character-id",
+  enableVideo: true,
 });
 
-convaiClient.on("connect", () => {
-  console.log("Connected");
-});
+// Disconnect
+await convaiClient.disconnect();
 
-convaiClient.on("disconnect", () => {
-  console.log("Disconnected");
-});
+// Reconnect
+await convaiClient.reconnect();
+
+// Reset session (clear conversation history)
+convaiClient.resetSession();
+
+// 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
 ```
 
 ### Messaging
 
-**Send Text Message:**
-
 ```typescript
+// Send text message
 convaiClient.sendUserTextMessage("Hello, how are you?");
-```
-
-**Send Trigger Message:**
 
-```typescript
-// Trigger specific character action
+// Send trigger message (invoke character action)
 convaiClient.sendTriggerMessage("greet", "User entered the room");
 
-// Trigger without message
-convaiClient.sendTriggerMessage("wave");
-```
+// Interrupt character's current response
+convaiClient.sendInterruptMessage();
 
-**Update Context:**
+// Update context
+convaiClient.updateTemplateKeys({ user_name: "John" });
+convaiClient.updateDynamicInfo({ text: "User is browsing products" });
 
-```typescript
-// Update template keys (e.g., user name, location)
-convaiClient.updateTemplateKeys({
-  user_name: "John",
-  location: "New York",
-});
+// Access messages
+console.log(convaiClient.chatMessages);
 
-// Update dynamic information
-convaiClient.updateDynamicInfo({
-  text: "User is currently browsing the products page",
-});
+// Access real-time user transcription
+console.log(convaiClient.userTranscription);
 ```
 
-**Message History:**
+### Audio Controls
 
 ```typescript
-// React
-const { chatMessages } = convaiClient;
+// Mute/unmute microphone
+await convaiClient.audioControls.muteAudio();
+await convaiClient.audioControls.unmuteAudio();
+await convaiClient.audioControls.toggleAudio();
 
-// Core API (event-based)
-convaiClient.on("message", (message: ChatMessage) => {
-  console.log("New message:", message.content);
-  console.log("Message type:", message.type);
-});
+// Check mute state
+console.log(convaiClient.isAudioMuted);
 
-convaiClient.on("messagesChange", (messages: ChatMessage[]) => {
-  console.log("All messages:", messages);
-});
-```
+// Get available microphones
+const devices = await convaiClient.audioControls.getAudioDevices();
 
-**Message Types:**
+// Set microphone
+await convaiClient.audioControls.setAudioDevice(deviceId);
 
-```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
+// Monitor audio level
+convaiClient.audioControls.startAudioLevelMonitoring();
+convaiClient.audioControls.on("audioLevelChange", (level) => {
+  console.log("Audio level:", level); // 0 to 1
+});
+convaiClient.audioControls.stopAudioLevelMonitoring();
 ```
 
-### State Monitoring
+### Video Controls
 
-**Agent State:**
+**⚠️ Requires `enableVideo: true` in config.**
 
 ```typescript
-// React
-const { state } = convaiClient;
+// Enable/disable camera
+await convaiClient.videoControls.enableVideo();
+await convaiClient.videoControls.disableVideo();
+await convaiClient.videoControls.toggleVideo();
 
-// Check specific states
-if (state.isListening) {
-  console.log("Bot is listening");
-}
+// Check video state
+console.log(convaiClient.isVideoEnabled);
 
-if (state.isThinking) {
-  console.log("Bot is thinking");
-}
+// Set video quality
+await convaiClient.videoControls.setVideoQuality("high"); // 'low' | 'medium' | 'high'
 
-if (state.isSpeaking) {
-  console.log("Bot is speaking");
-}
+// Get available cameras
+const devices = await convaiClient.videoControls.getVideoDevices();
 
-// Combined state
-console.log(state.agentState); // 'disconnected' | 'connected' | 'listening' | 'thinking' | 'speaking'
+// Switch camera
+await convaiClient.videoControls.setVideoDevice(deviceId);
 ```
 
-**User Transcription:**
-
-```typescript
-// React
-const { userTranscription } = convaiClient;
-
-// Core API (event-based)
-convaiClient.on("userTranscriptionChange", (transcription: string) => {
-  console.log("User is saying:", transcription);
-});
-```
+### Screen Share Controls
 
-**Bot Ready State:**
+**⚠️ Requires `enableVideo: true` in config.**
 
 ```typescript
-// React
-const { isBotReady } = convaiClient;
+// Start/stop screen share
+await convaiClient.screenShareControls.enableScreenShare();
+await convaiClient.screenShareControls.enableScreenShareWithAudio();
+await convaiClient.screenShareControls.disableScreenShare();
+await convaiClient.screenShareControls.toggleScreenShare();
 
-// Core API (event-based)
-convaiClient.on("botReady", () => {
-  console.log("Bot is ready to receive messages");
-});
+// Check screen share state
+console.log(convaiClient.isScreenShareActive);
 ```
 
-## Getting Convai Credentials
+---
+
+## Getting Credentials
 
 1. Visit [convai.com](https://convai.com) and create an account
 2. Navigate to your dashboard
@@ -816,41 +1282,71 @@ convaiClient.on("botReady", () => {
 4. Copy your **API Key** from the dashboard
 5. Copy your **Character ID** from the character details
 
-## Import Paths
+---
+
+## TypeScript Support
+
+All exports are fully typed:
+
+**React:**
 
 ```typescript
-// Default: React version (backward compatible)
-import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk";
+import type {
+  // Configuration
+  ConvaiConfig,
 
-// Explicit React import
-import { useConvaiClient, ConvaiWidget } from "@convai/web-sdk/react";
+  // State
+  ConvaiClientState,
 
-// Vanilla JS/TS
-import { ConvaiClient, createConvaiWidget } from "@convai/web-sdk/vanilla";
+  // Messages
+  ChatMessage,
+  ChatMessageType,
 
-// Core only (no UI, framework agnostic)
-import { ConvaiClient } from "@convai/web-sdk/core";
-```
+  // Client
+  IConvaiClient,
+  ConvaiClient,
 
-## TypeScript Support
+  // Controls
+  AudioControls,
+  VideoControls,
+  ScreenShareControls,
+} from "@convai/web-sdk/react";
+```
 
-All exports are fully typed:
+**Vanilla:**
 
 ```typescript
 import type {
-  ConvaiClient,
+  // Configuration
   ConvaiConfig,
+
+  // State
   ConvaiClientState,
+
+  // Messages
   ChatMessage,
+  ChatMessageType,
+
+  // Client
+  IConvaiClient,
+  ConvaiClient,
+
+  // Controls
   AudioControls,
   VideoControls,
   ScreenShareControls,
-  IConvaiClient,
-} from "@convai/web-sdk";
+
+  // Widget
+  VanillaWidget,
+  VanillaWidgetOptions,
+} from "@convai/web-sdk/vanilla";
 ```
 
+---
+
 ## Support
 
-- [Convai Forum](https://forum.convai.com)
-- [API Reference](./API_REFERENCE.md)
-- [Convai Website](https://convai.com)
+- **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)