@myned-ai/avatar-chat-widget 0.0.3 → 0.1.0

package/README.md

@@ -6,7 +6,7 @@
 
 ---
 
-## Installation
+## Quick Start
 
 ### Script Tag (No Build Required)
 
@@ -20,7 +20,6 @@ Add directly to any HTML page or website builder:
 <script src="https://cdn.jsdelivr.net/npm/@myned-ai/avatar-chat-widget"></script>
 
 <script>
-  // Initialize the widget
   AvatarChat.init({
     container: '#avatar-chat',
     serverUrl: 'wss://your-backend-server.com/ws',
@@ -30,9 +29,16 @@ Add directly to any HTML page or website builder:
 </script>
 ```
 
-### Programmatic Control
+### NPM Package
+
+```bash
+npm install @myned-ai/avatar-chat-widget
+```
 
 ```typescript
+import { AvatarChat } from '@myned-ai/avatar-chat-widget';
+import '@myned-ai/avatar-chat-widget/style.css';
+
 const chat = AvatarChat.init({
   container: '#avatar-chat',
   serverUrl: 'wss://your-backend-server.com/ws',
@@ -50,62 +56,84 @@ chat.destroy();  // Cleanup
 
 ---
 
-## Configuration Options
+## Configuration
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `container` | `string \| HTMLElement` | **required** | CSS selector or DOM element |
-| `serverUrl` | `string` | **required** | WebSocket server URL |
-| `position` | `string` | `'bottom-right'` | Position: `bottom-right`, `bottom-left`, `top-right`, `top-left`, `inline` |
-| `theme` | `string` | `'light'` | Theme: `light`, `dark`, `auto` |
+| `serverUrl` | `string` | **required** | WebSocket server URL (ws:// or wss://) |
+| `position` | `string` | `'bottom-right'` | `bottom-right`, `bottom-left`, `top-right`, `top-left`, `inline` |
+| `theme` | `string` | `'light'` | `light`, `dark`, `auto` (follows system preference) |
 | `startCollapsed` | `boolean` | `true` | Start minimized as bubble |
-| `width` | `number` | `380` | Widget width in pixels |
-| `height` | `number` | `550` | Widget height in pixels |
-| `logLevel` | `string` | `'error'` | Log level: `none`, `error`, `warn`, `info`, `debug` |
-| `customStyles` | `string` | `undefined` | Custom CSS to inject |
-| `authEnabled` | `boolean` | `true` | Enable HMAC token authentication |
+| `width` | `number` | `380` | Widget width (200-2000px) |
+| `height` | `number` | `550` | Widget height (300-2000px) |
+| `enableVoice` | `boolean` | `true` | Enable voice chat |
+| `enableText` | `boolean` | `true` | Enable text chat |
+| `logLevel` | `string` | `'error'` | `none`, `error`, `warn`, `info`, `debug` |
+| `customStyles` | `string` | `undefined` | Custom CSS to inject into Shadow DOM |
+| `authEnabled` | `boolean` | `true` | Enable HMAC authentication (disable for dev) |
+| `avatarUrl` | `string` | auto-detected | URL to avatar ZIP file |
 
 ### Callbacks
 
 | Callback | Type | Description |
 |----------|------|-------------|
-| `onReady` | `() => void` | Called when widget is initialized |
-| `onConnectionChange` | `(connected: boolean) => void` | Connection status changes |
-| `onMessage` | `(msg: {role, text}) => void` | Message received |
+| `onReady` | `() => void` | Widget initialized and ready |
+| `onConnectionChange` | `(connected: boolean) => void` | WebSocket connection status changed |
+| `onMessage` | `(msg: {role, text}) => void` | Message received from server |
 | `onError` | `(error: Error) => void` | Error occurred |
 
 ---
 
-## Development
+## Customization
 
-### Local Development
+### Changing Colors
 
-```bash
-# Install dependencies
-npm install
+The widget uses CSS variables that you can override with the `customStyles` option:
 
-# Start development server (SPA mode)
-npm run dev
-
-# Build library for distribution
-npm run build:lib
-
-# Build both SPA and library
-npm run build:all
-```
-
-### Test with Sample Backend Server
-
-```bash
-# Clone the avatar chat server
-git clone https://github.com/myned-ai/avatar-chat-server.git
-cd avatar-chat-server
-
-# Follow the instructions in the repository to start the Docker container
-docker-compose up
+```typescript
+AvatarChat.init({
+  container: '#avatar-chat',
+  serverUrl: 'wss://your-server.com/ws',
+  customStyles: `
+    /* Primary brand colors (gradient, buttons, user messages) */
+    .chat-bubble,
+    .chat-header {
+      background: linear-gradient(135deg, #ff6b6b 0%, #ee5a6f 100%) !important;
+    }
+
+    .input-button {
+      background: #ff6b6b !important;
+    }
+
+    .input-button:hover:not(:disabled) {
+      background: #ee5a6f !important;
+    }
+
+    .message.user .message-bubble {
+      background: #ff6b6b !important;
+    }
+
+    /* Avatar border */
+    .avatar-circle {
+      border-color: #ff6b6b !important;
+    }
+
+    /* Input focus color */
+    #chatInput:focus {
+      border-color: #ff6b6b !important;
+    }
+  `
+});
 ```
 
-The server will start on `ws://localhost:8765` by default.
+**Common color targets:**
+- `.chat-bubble` - Minimized bubble
+- `.chat-header` - Header gradient
+- `.avatar-circle` - Avatar border
+- `.input-button` - Send & mic buttons
+- `.message.user .message-bubble` - User message bubbles
+- `#chatInput:focus` - Input field focus state
 
 ---
 
@@ -115,181 +143,133 @@ The server will start on `ws://localhost:8765` by default.
 - **3D Avatar** - Gaussian Splatting rendering with 52 ARKit blendshapes
 - **Synchronized Animation** - Audio and facial expressions in perfect sync
 - **Auto-reconnection** - Resilient WebSocket with exponential backoff
-- **Shadow DOM** - CSS isolated, no style conflicts
-- **Accessible** - WCAG 2.1 AA compliant
+- **Shadow DOM** - Complete CSS isolation, no style conflicts
+- **Framework Agnostic** - Works with React, Vue, Angular, or vanilla HTML
+- **Accessible** - WCAG 2.1 AA compliant with ARIA labels
 
 ---
 
-## Avatar Rendering Engine
-
-This widget uses [@myned-ai/gsplat-flame-avatar-renderer](https://www.npmjs.com/package/@myned-ai/gsplat-flame-avatar-renderer), a specialized Gaussian Splatting library for rendering animated 3D avatars.
+## WebSocket Protocol
 
-### Animation States
+### Client → Server
 
-| State | Animation Index | Description |
-|-------|-----------------|-------------|
-| **Idle** | 1 | Subtle breathing and micro-movements |
-| **Hello** | 2 | Attentive greeting posture |
-| **Responding** | 6 | Speaking body movements (head sway, gestures) |
+```json
+{ "type": "text", "data": "Hello", "userId": "user_123", "timestamp": 1234567890 }
+{ "type": "audio", "data": "<ArrayBuffer>", "format": "audio/webm" }
+```
 
-### Eye Blink Behavior
+### Server → Client
 
-The widget handles all eye blinking on the frontend for consistent behavior across states. Blink intervals vary by avatar state:
+```json
+{ "type": "audio_start", "sessionId": "abc", "sampleRate": 24000 }
+{ "type": "audio_chunk", "data": "<ArrayBuffer>", "timestamp": 1234567890 }
+{ "type": "blendshape", "weights": {...}, "timestamp": 1234567890 }
+{ "type": "audio_end", "sessionId": "abc" }
+{ "type": "text", "data": "Hello", "timestamp": 1234567890 }
+```
 
-| State | Interval | Description |
-|-------|----------|-------------|
-| **Idle** | 2-4 seconds | Relaxed, natural blinking |
-| **Hello** | 1.8-3.5 seconds | Attentive, slightly more frequent |
-| **Responding** | 1.3-3.3 seconds | Natural speaking rate |
+---
 
-Each blink uses randomized patterns and intensity (80-100%) for natural variation.
+## Authentication
 
-### Avatar Asset Format
+### Disabling Auth (Development)
 
-The widget loads a modified LAM based avatar from ZIP file containing:
+For local testing without an auth server:
 
-```
-avatar.zip
-├── avatar/
-│   ├── offset.ply             # Gaussian splats point cloud
-│   ├── animation.glb          # Animation clips
-│   ├── skin.glb               # Skinning/skeleton data
-│   ├── vertex_order.json      # Vertex ordering
-│   └── iris_occlusion.json    # Iris occlusion ranges (optional)
+```typescript
+AvatarChat.init({
+  container: '#avatar-chat',
+  serverUrl: 'ws://localhost:8080/ws',
+  authEnabled: false  // Disable authentication
+});
 ```
 
-### Browser Requirements
+### Production Setup
 
-For production deployment, your server must send these headers to enable SharedArrayBuffer (used for high-performance sorting):
+The widget uses HMAC-SHA256 token authentication for secure connections:
 
-```
-Cross-Origin-Embedder-Policy: require-corp
-Cross-Origin-Opener-Policy: same-origin
-```
-
----
+1. Widget requests token from `POST /api/auth/token`
+2. Server validates origin and returns signed token
+3. Widget connects with token: `wss://server/ws?token=...`
+4. Server verifies signature and expiration
 
-## Directory Structure
-
-| Path | Files | Description |
-|------|-------|-------------|
-| `src/` | 3 | Entry points (`widget.ts`, `main.ts`, `config.ts`) |
-| `src/avatar/` | 3 | Avatar rendering (`GaussianAvatar`, `LazyAvatar`) |
-| `src/constants/` | 2 | ARKit blendshape constants |
-| `src/managers/` | 2 | Chat orchestration (`ChatManager`) |
-| `src/services/` | 8 | Core services (audio, WebSocket, blendshapes) |
-| `src/types/` | 4 | TypeScript type definitions |
-| `src/utils/` | 9 | Shared utilities (logging, buffers, protocols) |
-
-### Key Components
-
-| Component | Description |
-|-----------|-------------|
-| `widget.ts` | Main entry point, `AvatarChat.init()` API |
-| `ChatManager` | Orchestrates services, handles state transitions |
-| `GaussianAvatar` | Wrapper for gsplat-flame-avatar-renderer |
-| `SocketService` | WebSocket connection with auto-reconnect |
-| `AudioInput` | Microphone capture (PCM16 for OpenAI Realtime API) |
-| `AudioOutput` | Audio playback with Web Audio API |
-| `SyncPlayback` | Synchronized audio + blendshape playback |
-| `BlendshapeBuffer` | Frame buffer for smooth animation |
-| `AuthService` | HMAC token authentication |
-| `Logger` | Centralized logging with levels |
+**Security features:**
+- Origin validation (whitelist domains)
+- Time-limited tokens with auto-refresh
+- Rate limiting per domain/session
 
 ---
 
-## Architecture
-
-```
-Frontend (This Widget)        Backend (Your Server)
-┌─────────────────────┐      ┌──────────────────────┐
-│   Widget (Shadow)   │◄────►│   WebSocket Server   │
-│   ├─ Chat UI        │      │   ├─ AI/LLM          │
-│   ├─ Voice I/O      │      │   ├─ TTS             │
-│   └─ Avatar         │      │   └─ Blendshape Gen  │
-└─────────────────────┘      └──────────────────────┘
-```
+## Development
 
----
+### Local Setup
 
-## WebSocket Protocol
+```bash
+# Install dependencies
+npm install
 
-**Client to Server:**
-```json
-{ "type": "text", "data": "Hello", "userId": "user_123", "timestamp": 123 }
-{ "type": "audio", "data": "<ArrayBuffer>", "format": "audio/webm" }
-```
+# Start dev server with hot reload
+npm run dev
 
-**Server to Client:**
-```json
-{ "type": "audio_start", "sessionId": "abc", "sampleRate": 24000 }
-{ "type": "audio_chunk", "data": "<ArrayBuffer>", "timestamp": 124 }
-{ "type": "blendshape", "weights": {...}, "timestamp": 124 }
-{ "type": "audio_end", "sessionId": "abc" }
+# Build for production
+npm run build:lib
 ```
 
----
+### Testing with Backend
 
-## Authentication
+```bash
+# Clone sample server
+git clone https://github.com/myned-ai/avatar-chat-server.git
+cd avatar-chat-server
 
-The widget uses HMAC token authentication by default for secure WebSocket connections.
+# Start with Docker
+docker-compose up
+```
 
-### Disabling Authentication (Development)
+Server runs on `ws://localhost:8765` by default.
 
-For local development without an auth server:
+---
 
-```typescript
-AvatarChat.init({
-  container: '#avatar-chat',
-  serverUrl: 'ws://localhost:8080/ws',
-  authEnabled: false  // Disable for local testing
-});
-```
+## Browser Requirements
 
-### How It Works
+**Supported browsers:**
+- Chrome/Edge 90+
+- Firefox 89+
+- Safari 15.2+
 
-1. Widget requests a token from `POST /api/auth/token`
-2. Server validates origin and returns HMAC-signed token
-3. Widget connects to WebSocket with token: `ws://server/ws?token=...`
-4. Server verifies token signature and expiration
+**Production deployment:**
 
-### Authentication Flow
+For optimal performance, your server must send these headers to enable SharedArrayBuffer:
 
 ```
-Widget                          Server
-  │                               │
-  │  POST /api/auth/token         │
-  │  Origin: https://yoursite.com │
-  │──────────────────────────────►│
-  │                               │ Validate origin
-  │     {token, ttl, origin}      │ Generate HMAC token
-  │◄──────────────────────────────│
-  │                               │
-  │  WebSocket /ws?token=...      │
-  │──────────────────────────────►│
-  │                               │ Verify token
-  │        Connection OK          │ Check rate limits
-  │◄──────────────────────────────│
+Cross-Origin-Embedder-Policy: require-corp
+Cross-Origin-Opener-Policy: same-origin
 ```
 
-### Security Features
+---
+
+## Troubleshooting
 
-- **Origin validation** - Only whitelisted domains can connect
-- **HMAC-SHA256 tokens** - Cryptographically signed, time-limited
-- **Rate limiting** - Per-domain and per-session limits
-- **Auto-refresh** - Tokens refresh automatically before expiry
+### Widget not loading
+- Check browser console for errors
+- Verify `serverUrl` is correct WebSocket URL (ws:// or wss://)
+- Ensure container element exists before calling `init()`
 
-### Server Requirements
+### Avatar not rendering
+- Check server CORS headers (COEP/COOP)
+- Verify avatar ZIP file is accessible
+- Check `logLevel: 'debug'` for detailed logs
 
-The backend must implement:
-- `POST /api/auth/token` - Returns `{token, ttl, origin}`
-- WebSocket token verification via query parameter
+### Voice not working
+- Microphone permission required
+- HTTPS required for production (getUserMedia)
+- Check browser compatibility
 
 ---
 
-### Acknowledgement
+## Acknowledgements
 
-This work is built on many amazing research works and open-source projects:
+Built on amazing open-source research:
 - [OpenLRM](https://github.com/3DTopia/OpenLRM)
 - [GAGAvatar](https://github.com/xg-chu/GAGAvatar)
 - [GaussianAvatars](https://github.com/ShenhanQian/GaussianAvatars)

package/dist/avatar-chat-widget.d.ts

@@ -1,3 +1,6 @@
+import { AvatarChatConfig } from './widget/types';
+import { AvatarChatInstance } from './widget/types';
+
 /**
  * AvatarChat - Public Widget API
  */
@@ -6,6 +9,11 @@ declare const AvatarChat: {
     version: string;
     /** Active instance */
     _instance: AvatarChatElement | null;
+    /**
+     * Get the URL for the default included avatar
+     * Auto-detects CDN usage and returns the appropriate URL
+     */
+    getDefaultAvatarUrl(): string;
     /**
      * Initialize and mount the widget
      */
@@ -22,72 +30,7 @@ declare const AvatarChat: {
 export { AvatarChat }
 export default AvatarChat;
 
-/**
- * Avatar Chat Widget - Embeddable Web Component
- *
- * A real-time voice/text chat widget with 3D avatar animation.
- * Uses Shadow DOM for complete CSS isolation from host page.
- *
- * @example Script Tag (Wix, WordPress, HTML)
- * ```html
- * <div id="avatar-chat"></div>
- * <script src="https://cdn.jsdelivr.net/npm/@myned-ai/avatar-chat-widget"></script>
- * <script>
- *   AvatarChat.init({
- *     container: '#avatar-chat',
- *     serverUrl: 'wss://your-server.com/ws'
- *   });
- * </script>
- * ```
- *
- * @example NPM Package
- * ```typescript
- * import { AvatarChat } from 'avatar-chat-widget';
- * const widget = AvatarChat.init({ container: '#chat', serverUrl: 'wss://...' });
- * ```
- */
-/**
- * Widget configuration options passed at runtime
- */
-export declare interface AvatarChatConfig {
-    /** CSS selector or HTMLElement for the widget container (required) */
-    container: string | HTMLElement;
-    /** WebSocket server URL (required) */
-    serverUrl: string;
-    /** Widget position when using floating mode */
-    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'inline';
-    /** UI theme */
-    theme?: 'light' | 'dark' | 'auto';
-    /** Start in collapsed state (bubble only) */
-    startCollapsed?: boolean;
-    /** Widget width in pixels (default: 380) */
-    width?: number;
-    /** Widget height in pixels (default: 550) */
-    height?: number;
-    /** Enable/disable voice input (default: true) */
-    enableVoice?: boolean;
-    /** Enable/disable text input (default: true) */
-    enableText?: boolean;
-    /** Path to avatar model (default: './asset/nyx.zip') */
-    avatarUrl?: string;
-    /** Enable authentication (default: false) */
-    authEnabled?: boolean;
-    /** Log level for debugging */
-    logLevel?: 'none' | 'error' | 'warn' | 'info' | 'debug';
-    /** Custom CSS to inject (optional) */
-    customStyles?: string;
-    /** Callback when widget is ready */
-    onReady?: () => void;
-    /** Callback when connection state changes */
-    onConnectionChange?: (connected: boolean) => void;
-    /** Callback when a message is received */
-    onMessage?: (message: {
-        role: 'user' | 'assistant';
-        text: string;
-    }) => void;
-    /** Callback on error */
-    onError?: (error: Error) => void;
-}
+export { AvatarChatConfig }
 
 declare class AvatarChatElement extends HTMLElement {
     private shadow;
@@ -97,6 +40,8 @@ declare class AvatarChatElement extends HTMLElement {
     private _isMounted;
     private _isConnected;
     private _isCollapsed;
+    private themeMediaQuery;
+    private themeChangeHandler;
     constructor();
     /**
      * Configure the widget (call before mount)
@@ -127,7 +72,7 @@ declare class AvatarChatElement extends HTMLElement {
      */
     private setupUIEvents;
     /**
-     * Update connection status UI
+     * Update connection status (stub - connection indicator removed from UI)
      */
     private updateConnectionStatus;
     /**
@@ -158,34 +103,17 @@ declare class AvatarChatElement extends HTMLElement {
      * Check if connected to server
      */
     isServerConnected(): boolean;
+    /**
+     * Manually reconnect to the server
+     * Useful after network changes or connection failures
+     */
+    reconnect(): Promise<void>;
     /**
      * Cleanup
      */
     destroy(): void;
 }
 
-/**
- * Widget instance returned by init()
- */
-export declare interface AvatarChatInstance {
-    /** Send a text message */
-    sendMessage(text: string): void;
-    /** Mount widget to DOM (called automatically by init) */
-    mount(): void;
-    /** Destroy and cleanup widget */
-    destroy(): void;
-    /** Show the widget */
-    show(): void;
-    /** Hide the widget */
-    hide(): void;
-    /** Expand from collapsed state */
-    expand(): void;
-    /** Collapse to bubble */
-    collapse(): void;
-    /** Check if widget is mounted */
-    isMounted(): boolean;
-    /** Check if connected to server */
-    isConnected(): boolean;
-}
+export { AvatarChatInstance }
 
 export { }