@cuekit-ai/react 1.0.0 → 1.1.2

package/README.md

@@ -1,289 +1,414 @@
-# CueKit Web SDK
+# @cuekit-ai/react
 
-A powerful voice-controlled navigation and interaction SDK for React applications. CueKit enables users to navigate and interact with web applications using natural voice commands, providing an accessible and intuitive user experience.
+A powerful React SDK for integrating AI-powered voice interactions into your web applications. Built with TypeScript and designed for seamless voice navigation, commands, and interactions.
+
+[![npm version](https://badge.fury.io/js/%40cuekit-ai%2Freact.svg)](https://badge.fury.io/js/%40cuekit-ai%2Freact)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## 🚀 Features
 
-- **Voice Recognition**: Real-time speech-to-text using Web Speech API
-- **Text-to-Speech**: Built-in TTS for audio feedback
-- **Smart Navigation**: Automatic route detection and navigation
-- **Element Interaction**: Click buttons and interact with UI elements via voice commands
-- **Screen Context Awareness**: Captures and analyzes current screen elements
-- **Cross-Platform**: Works with any React application (Next.js, Create React App, etc.)
-- **Customizable UI**: Flexible microphone button with multiple positioning options
-- **TypeScript Support**: Full TypeScript support with comprehensive type definitions
+- **🎤 Voice Recognition**: Real-time speech-to-text with high accuracy
+- **🤖 AI-Powered Navigation**: Intelligent voice commands for app navigation
+- **🎯 Intent Recognition**: Understands user intent and performs actions
+- **🔊 Text-to-Speech**: Natural voice responses using ElevenLabs
+- **🎨 Beautiful UI**: Modern, animated voice assistant interface
+- **📱 Responsive Design**: Works seamlessly across all devices
+- **⚡ Real-time Processing**: Instant voice command processing
+- **🔄 State Management**: Robust state handling for voice interactions
+- **🎭 Portal Rendering**: Modal components render at document body level
+- **✨ Visual Feedback**: Border glow effects and animations
 
 ## 📦 Installation
 
 ```bash
-npm install cuekit-web-sdk
-# or
-yarn add cuekit-web-sdk
+npm install @cuekit-ai/react
+```
+
+```bash
+yarn add @cuekit-ai/react
 ```
 
-## 🏗️ Quick Start
+```bash
+pnpm add @cuekit-ai/react
+```
 
-### 1. Initialize CueKit
+## 🎯 Quick Start
 
-Wrap your app with the `CuekitProvider`:
+### 1. Wrap your app with CuekitProvider
 
 ```tsx
-import { CuekitProvider } from 'cuekit-web-sdk'
+import { CuekitProvider } from '@cuekit-ai/react'
 
 function App() {
   return (
-    <CuekitProvider apiKey="your-api-key" appId="your-app-id" deviceId="optional-device-id">
-      <YourApp />
-    </CuekitProvider>
+  <CuekitProvider
+  apiKey="your-api-key"
+  appId="your-app-id"
+  deviceId="optional-device-id"
+  navigationHandler={(path, params) => {
+    const qs = params ? `?${new URLSearchParams(params).toString()}` : ''
+    // Example with Next.js App Router
+    router.push(`${path}${qs}`)
+    // Or with React Router v6
+    // navigate(`${path}${qs}`)
+  }}
   )
 }
 ```
 
-### 2. Add Voice Control Button
-
-Add the `MicButton` component to enable voice interactions:
+### 2. Add the MicButton component
 
 ```tsx
-import { MicButton } from 'cuekit-web-sdk'
+import { MicButton } from '@cuekit-ai/react'
 
 function YourApp() {
   return (
     <div>
-      {/* Your app content */}
-      <MicButton screenPosition="bottom-right" buttonSize={60} hasText={false} />
+      <h1>My Voice-Enabled App</h1>
+      <MicButton
+        screenPosition="bottom-right"
+        buttonStyle={{
+          backgroundColor: 'blue',
+          borderRadius: '50%',
+        }}
+      />
     </div>
   )
 }
 ```
 
-### 3. Initialize the SDK
+## 🎨 Components
 
-Call `InitCuekit` with your API key:
+### MicButton
 
-```tsx
-import { InitCuekit } from 'cuekit-web-sdk'
+The main voice interaction component with a beautiful animated interface.
 
-// Initialize with API key
-InitCuekit('your-api-key')
+```tsx
+import { MicButton } from '@cuekit-ai/react'
+;<MicButton
+  screenPosition="bottom-right" // 'bottom-left' | 'bottom-center' | 'bottom-right'
+  buttonStyle={
+    {
+      /* custom styles */
+    }
+  }
+  buttonSize={60}
+  hasText={false}
+  text="Voice Assistant"
+  textStyle={
+    {
+      /* text styles */
+    }
+  }
+  imageSource="path/to/image.png"
+  imageStyle={
+    {
+      /* image styles */
+    }
+  }
+/>
 ```
 
-## 🎯 Core Components
+#### Props
+
+| Prop             | Type                                                 | Default          | Description                          |
+| ---------------- | ---------------------------------------------------- | ---------------- | ------------------------------------ |
+| `screenPosition` | `'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-right'` | Position of the mic button           |
+| `buttonStyle`    | `React.CSSProperties`                                | `{}`             | Custom styles for the button         |
+| `buttonSize`     | `number`                                             | `60`             | Size of the button in pixels         |
+| `hasText`        | `boolean`                                            | `false`          | Whether to show text with the button |
+| `text`           | `string`                                             | `'CueKit VC'`    | Text to display with the button      |
+| `textStyle`      | `React.CSSProperties`                                | `{}`             | Styles for the text                  |
+| `imageSource`    | `string`                                             | `undefined`      | Image source for the button          |
+| `imageStyle`     | `React.CSSProperties`                                | `{}`             | Styles for the image                 |
 
 ### CuekitProvider
 
-The main provider component that sets up the voice control context.
+The context provider that initializes the voice assistant.
 
 ```tsx
-<CuekitProvider
+import { CuekitProvider } from '@cuekit-ai/react'
+
+;<CuekitProvider
   apiKey="your-api-key"
   appId="your-app-id"
   deviceId="optional-device-id"
-  navigator={router} // Optional: Pass your router instance
+  navigationHandler={(path, params) => {
+    const qs = params ? `?${new URLSearchParams(params).toString()}` : ''
+    // Example with Next.js App Router
+    router.push(`${path}${qs}`)
+    // Or with React Router v6
+    // navigate(`${path}${qs}`)
+  }}
 >
   {children}
 </CuekitProvider>
 ```
 
-**Props:**
+#### Props
 
-- `apiKey` (required): Your CueKit API key
-- `appId` (required): Your application ID
-- `deviceId` (optional): Unique device identifier
-- `navigator` (optional): Router instance for navigation
-- `children`: React components to wrap
+| Prop                | Type                                                   | Required | Description                                                                |
+| ------------------- | ------------------------------------------------------ | -------- | -------------------------------------------------------------------------- |
+| `apiKey`            | `string`                                               | ✅       | Your CueKit API key                                                        |
+| `appId`             | `string`                                               | ✅       | Your application ID                                                        |
+| `deviceId`          | `string`                                               | ❌       | Unique device identifier (auto-generated if not provided)                  |
+| `navigationHandler` | `(path: string, params?: Record<string, any>) => void` | ❌       | Custom router handler. If not provided, falls back to internal navigation. |
+| `children`          | `ReactNode`                                            | ✅       | Your app components                                                        |
 
-### MicButton
+### Routing integration
+
+You can integrate your app's router by passing a `navigationHandler` to `CuekitProvider`.
 
-A customizable microphone button for voice input.
+Next.js App Router example:
 
 ```tsx
-<MicButton
-  hasText={false}
-  text="Voice Control"
-  screenPosition="bottom-right"
-  buttonSize={60}
-  imageSource="path/to/mic-icon.png"
-  buttonStyle={{ backgroundColor: '#007bff' }}
-/>
+'use client'
+import { useEffect } from 'react'
+import { useRouter } from 'next/navigation'
+import { CuekitProvider } from '@cuekit-ai/react'
+
+export default function Providers({ children }: { children: React.ReactNode }) {
+  const router = useRouter()
+
+  return (
+    <CuekitProvider
+      apiKey={process.env.NEXT_PUBLIC_CUEKIT_API_KEY!}
+      appId={process.env.NEXT_PUBLIC_CUEKIT_APP_ID!}
+      navigationHandler={(path, params) => {
+        const qs = params ? `?${new URLSearchParams(params).toString()}` : ''
+        router.push(`${path}${qs}`)
+      }}
+    >
+      {children}
+    </CuekitProvider>
+  )
+}
 ```
 
-**Props:**
+React Router v6 example:
 
-- `hasText` (optional): Show text instead of icon
-- `text` (optional): Button text when `hasText` is true
-- `textStyle` (optional): Custom styles for text
-- `imageSource` (optional): Custom microphone icon URL
-- `imageStyle` (optional): Custom styles for image
-- `buttonStyle` (optional): Custom button styles
-- `screenPosition` (optional): Button position (`'bottom-right'`, `'bottom-left'`, `'bottom-center'`)
-- `buttonSize` (optional): Button size in pixels
+```tsx
+import { useNavigate } from 'react-router-dom'
+import { CuekitProvider } from '@cuekit-ai/react'
+
+function AppProviders({ children }: { children: React.ReactNode }) {
+  const navigate = useNavigate()
+
+  return (
+    <CuekitProvider
+      apiKey={import.meta.env.VITE_CUEKIT_API_KEY}
+      appId={import.meta.env.VITE_CUEKIT_APP_ID}
+      navigationHandler={(path, params) => {
+        const qs = params ? `?${new URLSearchParams(params).toString()}` : ''
+        navigate(`${path}${qs}`)
+      }}
+    >
+      {children}
+    </CuekitProvider>
+  )
+}
+```
 
-## 🎤 Voice Recognition
+## 🔧 Hooks
 
-### useVoice Hook
+### useVoice
 
-Custom hook for voice recognition functionality:
+Hook for voice recognition and processing.
 
 ```tsx
-import { useVoice } from 'cuekit-web-sdk'
+import { useVoice } from '@cuekit-ai/react'
 
-function VoiceComponent() {
+function MyComponent() {
   const { isListening, start, stop, transcript } = useVoice()
 
-  const handleVoiceToggle = async () => {
-    if (isListening) {
-      await stop()
-    } else {
-      await start('Hello, how can I help you?')
-    }
+  const handleVoiceStart = () => {
+    start('Hello, how can I help you?')
   }
 
-  return <button onClick={handleVoiceToggle}>{isListening ? 'Stop' : 'Start'} Voice</button>
+  const handleVoiceStop = () => {
+    stop()
+  }
+
+  return (
+    <div>
+      <p>Listening: {isListening ? 'Yes' : 'No'}</p>
+      <p>Transcript: {transcript}</p>
+      <button onClick={handleVoiceStart}>Start Listening</button>
+      <button onClick={handleVoiceStop}>Stop Listening</button>
+    </div>
+  )
 }
 ```
 
-### useVoiceRecognition Hook
+### useAudioController
 
-Lower-level hook for speech recognition:
+Hook for audio playback control.
 
 ```tsx
-import { useVoiceRecognition } from 'cuekit-web-sdk'
+import { useAudioController } from '@cuekit-ai/react'
 
-function CustomVoiceComponent() {
-  const { isListening, startListening, stopListening, speechText } = useVoiceRecognition('en-US')
+function AudioComponent() {
+  const { play, pause, stop, isPlaying } = useAudioController()
 
-  // Custom voice recognition logic
+  return (
+    <div>
+      <button onClick={play}>Play</button>
+      <button onClick={pause}>Pause</button>
+      <button onClick={stop}>Stop</button>
+      <p>Playing: {isPlaying ? 'Yes' : 'No'}</p>
+    </div>
+  )
 }
 ```
 
-## 🔧 Advanced Usage
+### useVoiceRecognition
 
-### Custom Voice Processing
-
-Process voice input manually:
+Hook for advanced voice recognition features.
 
 ```tsx
-import { processVoice } from 'cuekit-web-sdk'
+import { useVoiceRecognition } from '@cuekit-ai/react'
 
-const handleVoiceInput = async (transcript: string) => {
-  const result = await processVoice(transcript, 'your-api-key', 'your-app-id', 'device-id')
+function VoiceRecognitionComponent() {
+  const { isListening, transcript, startListening, stopListening, resetTranscript } =
+    useVoiceRecognition()
 
-  console.log('Voice processing result:', result)
+  return (
+    <div>
+      <button onClick={startListening}>Start</button>
+      <button onClick={stopListening}>Stop</button>
+      <button onClick={resetTranscript}>Reset</button>
+      <p>Transcript: {transcript}</p>
+    </div>
+  )
 }
 ```
 
-### Audio Controller
+## 🛠️ Utilities
+
+### processVoice
 
-Manage text-to-speech functionality:
+Process voice commands and execute actions.
 
 ```tsx
-import { useAudioController } from 'cuekit-web-sdk'
+import { processVoice } from '@cuekit-ai/react'
 
-function AudioComponent() {
-  const { speak, stop, isSpeaking } = useAudioController()
+const handleVoiceCommand = async (transcript: string) => {
+  const result = await processVoice(transcript, apiKey, appId, deviceId)
 
-  const handleSpeak = () => {
-    speak('Hello, this is a test message')
+  if (result) {
+    console.log('Voice command processed:', result)
   }
-
-  return (
-    <div>
-      <button onClick={handleSpeak}>Speak</button>
-      <button onClick={stop}>Stop</button>
-      {isSpeaking && <span>Speaking...</span>}
-    </div>
-  )
 }
 ```
 
-### Navigation Integration
+### onStateChange
 
-For custom navigation handling:
+Handle navigation state changes.
 
 ```tsx
-import { onStateChange } from 'cuekit-web-sdk'
+import { onStateChange } from '@cuekit-ai/react'
 
-// Call this when your app's route changes
-onStateChange()
+// Automatically called by CuekitProvider
+// Handles route changes and voice command re-triggering
 ```
 
-## 🎨 Customization
+## 🎯 Voice Commands
+
+The SDK supports various voice commands for navigation and interaction:
+
+### Navigation Commands
+
+- "Go to home"
+- "Navigate to settings"
+- "Open profile page"
+- "Go back"
+
+### Action Commands
+
+- "Click the submit button"
+- "Press the login button"
+- "Select the first option"
+- "Scroll down"
+
+### Information Commands
 
-### Styling the MicButton
+- "What's on this page?"
+- "Tell me about this screen"
+- "What can I do here?"
+
+## 🎨 Styling
+
+### Custom Button Styling
 
 ```tsx
 <MicButton
   buttonStyle={{
-    backgroundColor: '#ff6b6b',
-    boxShadow: '0 4px 12px rgba(0,0,0,0.3)',
-    border: '2px solid #fff',
-  }}
-  textStyle={{
-    fontSize: '16px',
-    fontWeight: 'bold',
-    color: '#fff',
+    backgroundColor: 'linear-gradient(45deg, #667eea 0%, #764ba2 100%)',
+    boxShadow: '0 4px 15px rgba(0, 0, 0, 0.2)',
+    transform: 'scale(1.1)',
   }}
 />
 ```
 
-### Custom Positioning
+### Custom Modal Styling
 
-```tsx
-// Bottom right (default)
-<MicButton screenPosition="bottom-right" />
+The modal automatically adapts to your app's theme and provides:
 
-// Bottom left
-<MicButton screenPosition="bottom-left" />
+- Beautiful gradient backgrounds
+- Smooth animations
+- Responsive design
+- Accessibility features
 
-// Bottom center
-<MicButton screenPosition="bottom-center" />
+```env
+CUEKIT_API_KEY=your-api-key
+CUEKIT_APP_ID=your-app-id
+CUEKIT_DEVICE_ID=optional-device-id
 ```
 
-## 🔌 API Integration
+### API Configuration
 
-The SDK automatically sends component data to the CueKit API for intelligent voice processing. The API analyzes:
+The SDK communicates with the CueKit API for:
 
-- Current screen elements (buttons, links, etc.)
-- User voice input
-- Screen context
-- Navigation patterns
+- Voice command processing
+- Intent recognition
+- Navigation handling
+- Text-to-speech synthesis
 
-### API Response Format
+## 🔒 Security
 
-```typescript
-interface CueKitResponse {
-  actionType: 'navigate' | 'click' | 'audio_only'
-  routeName?: string
-  component?: {
-    hash: string
-    text: string
-    componentType: string
-  }
-  text?: string
-  claudeError?: boolean
-  errorMessage?: string
-}
-```
+- All API calls are made over HTTPS
+- API keys are stored securely
+- No sensitive data is logged
+- Device IDs are anonymized
 
-## 🔒 Security
+## 🚀 Performance
+
+- Lightweight bundle (~40KB gzipped)
+- Optimized for React 18+
+- Efficient re-rendering
+- Minimal memory footprint
+
+## 🐛 Troubleshooting
 
-- API keys are stored securely in the global context
-- Device IDs are automatically generated and persisted
-- Network requests are validated and error-handled
-- No sensitive data is logged to console
+### Common Issues
 
-## 🌐 Browser Support
+1. **Mic not working**
 
-- Chrome/Chromium (recommended)
-- Firefox
-- Safari (limited TTS support)
-- Edge
+   - Check browser permissions
+   - Ensure HTTPS connection
+   - Verify API key is valid
 
-**Note**: Voice recognition requires HTTPS in production environments.
+2. **Voice commands not recognized**
 
-## 📝 License
+   - Check internet connection
+   - Verify app ID is correct
+   - Ensure proper CuekitProvider setup
 
-This project is licensed under the MIT License.
+3. **Modal not appearing**
+   - Check z-index conflicts
+   - Verify portal rendering
+   - Ensure proper state management
 
+---
 
-**CueKit Web SDK** - Making web applications voice-controlled and accessible.
+**Made with ❤️ by [CueKit](https://cuekit.ai)**

package/dist/index.d.mts

@@ -19,7 +19,7 @@ type Props = {
     deviceId?: string;
     appId: string;
     children: ReactNode;
-    navigator?: any;
+    navigationHandler?: (path: string, params?: Record<string, any>) => void;
 };
 declare const CuekitProvider: React.FC<Props>;
 
@@ -29,6 +29,11 @@ declare const useAudioController: () => {
     play: (url: string) => Promise<void>;
 };
 
+type NavigationHandler = (path: string, params?: Record<string, any>) => void;
+declare const setNavigator: (navigator: any) => void;
+declare const setNavigationHandler: (handler: NavigationHandler | null) => void;
+declare const navigate: (path: string, params?: Record<string, any>) => void;
+declare const safeNavigate: (name: string | undefined, params?: Record<string, any>) => void;
 declare function onStateChange(): void;
 
 type ScreenPosition = 'bottom-center' | 'bottom-left' | 'bottom-right';
@@ -46,7 +51,7 @@ type MicButtonProps = {
 
 declare const MicButton: React.FC<MicButtonProps>;
 
-declare function InitCuekit(apiKey: string, navigator?: any): void;
+declare function InitCuekit(apiKey: string): void;
 
 declare const useVoiceRecognition: (lang?: string) => {
     isListening: boolean;
@@ -55,4 +60,4 @@ declare const useVoiceRecognition: (lang?: string) => {
     speechText: string;
 };
 
-export { CuekitProvider, InitCuekit, MicButton, onStateChange, processVoice, useAudioController, useVoiceRecognition };
+export { CuekitProvider, InitCuekit, MicButton, navigate, onStateChange, processVoice, safeNavigate, setNavigationHandler, setNavigator, useAudioController, useVoiceRecognition };

package/dist/index.d.ts

@@ -19,7 +19,7 @@ type Props = {
     deviceId?: string;
     appId: string;
     children: ReactNode;
-    navigator?: any;
+    navigationHandler?: (path: string, params?: Record<string, any>) => void;
 };
 declare const CuekitProvider: React.FC<Props>;
 
@@ -29,6 +29,11 @@ declare const useAudioController: () => {
     play: (url: string) => Promise<void>;
 };
 
+type NavigationHandler = (path: string, params?: Record<string, any>) => void;
+declare const setNavigator: (navigator: any) => void;
+declare const setNavigationHandler: (handler: NavigationHandler | null) => void;
+declare const navigate: (path: string, params?: Record<string, any>) => void;
+declare const safeNavigate: (name: string | undefined, params?: Record<string, any>) => void;
 declare function onStateChange(): void;
 
 type ScreenPosition = 'bottom-center' | 'bottom-left' | 'bottom-right';
@@ -46,7 +51,7 @@ type MicButtonProps = {
 
 declare const MicButton: React.FC<MicButtonProps>;
 
-declare function InitCuekit(apiKey: string, navigator?: any): void;
+declare function InitCuekit(apiKey: string): void;
 
 declare const useVoiceRecognition: (lang?: string) => {
     isListening: boolean;
@@ -55,4 +60,4 @@ declare const useVoiceRecognition: (lang?: string) => {
     speechText: string;
 };
 
-export { CuekitProvider, InitCuekit, MicButton, onStateChange, processVoice, useAudioController, useVoiceRecognition };
+export { CuekitProvider, InitCuekit, MicButton, navigate, onStateChange, processVoice, safeNavigate, setNavigationHandler, setNavigator, useAudioController, useVoiceRecognition };