@bod.ee/ai-avatar 1.0.0

package/README.md

@@ -0,0 +1,444 @@
+# Avatar Studio - AI Agent Component
+
+An interactive avatar component designed for AI systems with both programmable API and scripting language support. Perfect for chatbots, virtual assistants, and AI-powered applications.
+
+## Features
+
+- 🎭 **30+ Expressive Facial Expressions** - From happy to surprised, tired to excited
+- 👄 **Phoneme-Based Mouth Shapes** - Support for A, E, I, O, U, M, F, W phonemes
+- 🎬 **Animation Sequences** - Pre-built sequences and custom timing
+- 📝 **Declarative Scripting Language** - Simple, human-readable script syntax
+- 🔌 **Framework-Agnostic Core** - Works with React, Vue, or vanilla JS
+- 🎯 **Dual Interface** - Both API and script-based control
+- ⚡ **Lightweight & Performant** - Optimized for real-time interactions
+- 👀 **Cursor Tracking** - Eyes follow mouse movement
+- ✨ **Glitch Effects** - Personality-rich transitions
+
+## Quick Start
+
+### Installation
+
+```bash
+git clone <YOUR_GIT_URL>
+cd ai-avatar
+npm install
+npm run dev
+```
+
+Visit `http://localhost:8080` to see the demo.
+
+## Usage
+
+### React Hook (Recommended for React apps)
+
+```tsx
+import { useAvatarController } from '@/lib/avatar';
+import Avatar from '@/components/Avatar';
+
+function MyApp() {
+  const controller = useAvatarController({ autoAnimate: true });
+
+  return (
+    <div>
+      <Avatar controller={controller} />
+      <button onClick={() => controller.setExpression('happy')}>
+        Make Happy
+      </button>
+    </div>
+  );
+}
+```
+
+### Core Controller (Framework-agnostic)
+
+```typescript
+import { AvatarControllerClass } from '@/lib/avatar';
+
+const controller = new AvatarControllerClass({ autoAnimate: true });
+
+// API control
+controller.setExpression('happy');
+await controller.playSequence('greeting');
+await controller.blink();
+
+// Listen to events
+controller.on('stateChange', (state) => {
+  console.log('State changed:', state);
+});
+
+controller.on('expressionChange', (id) => {
+  console.log('Expression changed to:', id);
+});
+```
+
+### Scripting Language
+
+```typescript
+import { executeScript } from '@/lib/scripting';
+import { AvatarControllerClass } from '@/lib/avatar';
+
+const controller = new AvatarControllerClass();
+
+const script = `
+  EXPRESSION neutral
+  PAUSE 500ms
+  BLINK
+  SPEAK "Hello everyone!"
+  EXPRESSION happy
+  SEQUENCE cheerful
+`;
+
+await executeScript(script, controller);
+```
+
+## Script Syntax Reference
+
+### Commands
+
+| Command | Syntax | Description |
+|---------|--------|-------------|
+| **EXPRESSION** | `EXPRESSION <id>` | Set facial expression |
+| **PAUSE** | `PAUSE <duration>` | Wait (e.g., 1s, 500ms) |
+| **BLINK** | `BLINK [duration]` | Trigger eye blink |
+| **SEQUENCE** | `SEQUENCE <id>` | Play animation sequence |
+| **SPEAK** | `SPEAK "<text>"` | Display speech text* |
+| **LOOK_LEFT** | `LOOK_LEFT` | Look to the left |
+| **LOOK_RIGHT** | `LOOK_RIGHT` | Look to the right |
+| **LOOK_UP** | `LOOK_UP` | Look upward |
+| **LOOK_DOWN** | `LOOK_DOWN` | Look downward |
+| **REPEAT** | `REPEAT <n> { ... }` | Loop commands |
+
+*Note: TTS integration planned for future release
+
+### Example Scripts
+
+**Simple Greeting:**
+```
+EXPRESSION neutral
+PAUSE 500ms
+BLINK
+SPEAK "Hello! I'm your AI assistant."
+EXPRESSION happy
+PAUSE 2s
+```
+
+**Presentation Mode:**
+```
+EXPRESSION neutral
+SPEAK "Welcome to today's presentation."
+PAUSE 1s
+LOOK_RIGHT
+PAUSE 800ms
+SPEAK "Let me show you something interesting."
+EXPRESSION excited
+```
+
+**Loop Example:**
+```
+REPEAT 3 {
+  BLINK
+  PAUSE 800ms
+}
+EXPRESSION neutral
+```
+
+More examples available in `src/examples/scripts.ts`.
+
+## API Reference
+
+### AvatarControllerClass
+
+```typescript
+class AvatarControllerClass {
+  // Core methods
+  setExpression(id: string): void
+  setState(state: Partial<AvatarState>): void
+  blink(duration?: number): Promise<void>
+  playSequence(id: string): Promise<void>
+  stopSequence(): void
+  setAutoAnimate(enabled: boolean): void
+
+  // Getters
+  getState(): Readonly<AvatarState>
+  getCurrentExpression(): string | null
+  getExpressions(): ExpressionConfig[]
+  getSequences(): AnimationSequence[]
+  isAnimating(): boolean
+
+  // Lifecycle
+  destroy(): void
+
+  // Events (inherited from EventEmitter)
+  on(event: 'stateChange', handler: (state: AvatarState) => void): void
+  on(event: 'expressionChange', handler: (id: string) => void): void
+  on(event: 'sequenceStart', handler: (id: string) => void): void
+  on(event: 'sequenceEnd', handler: (id: string) => void): void
+  on(event: 'autoAnimateChange', handler: (enabled: boolean) => void): void
+}
+```
+
+### Available Expressions
+
+**Base States:**
+- `neutral`, `blink`
+
+**Happy States:**
+- `happy`, `happySmall`, `happyBig`, `cheerful`, `excited`
+
+**Squint Variations:**
+- `squintLight`, `squintMedium`, `squint`, `squintDeep`
+
+**Tired States:**
+- `focused`, `tired`, `sleepy`
+
+**Looking Directions:**
+- `lookLeft`, `lookRight`, `lookUp`, `lookDown`
+
+**Emotional:**
+- `surprised`, `curious`, `skeptical`, `shy`
+
+**Talking/Phonemes:**
+- `talking1`, `talking2`, `talking3`
+- `talking-A`, `talking-E`, `talking-I`, `talking-O`, `talking-U`, `talking-M`, `talking-F`, `talking-W`
+
+### Available Sequences
+
+- `blink`, `doubleBlink`, `slowBlink`
+- `greeting`, `cheerful`, `wakeUp`
+- `thinking`, `curiousScan`
+- `demoLoop`, `idle`
+
+(See `src/lib/avatar/sequences.ts` for complete list)
+
+## AI Integration
+
+### LLM Script Generation
+
+Train your LLM to generate scripts dynamically:
+
+```typescript
+const prompt = `Generate an avatar script for: ${userRequest}
+
+Available commands:
+- EXPRESSION <id>
+- PAUSE <duration>
+- BLINK
+- SEQUENCE <id>
+- SPEAK "<text>"
+- LOOK_LEFT/RIGHT/UP/DOWN
+- REPEAT <n> { ... }
+
+Output only the script, no explanations.`;
+
+const aiScript = await llm.generate(prompt);
+await executeScript(aiScript, controller);
+```
+
+### Direct API Integration
+
+```typescript
+class AIAgent {
+  private controller: AvatarControllerClass;
+
+  constructor() {
+    this.controller = new AvatarControllerClass();
+  }
+
+  async respondToUser(message: string) {
+    // Set thinking expression
+    this.controller.setExpression('focused');
+
+    // Generate response
+    const response = await this.llm.chat(message);
+
+    // Show happy while speaking
+    this.controller.setExpression('happy');
+
+    // Speak (with future TTS integration)
+    await this.speakText(response);
+
+    // Return to neutral
+    this.controller.setExpression('neutral');
+  }
+}
+```
+
+## Architecture
+
+### Project Structure
+
+```
+src/
+├── lib/
+│   ├── avatar/              # Core avatar system
+│   │   ├── types.ts         # TypeScript definitions
+│   │   ├── expressions.ts   # Expression registry
+│   │   ├── sequences.ts     # Animation sequences
+│   │   ├── AvatarController.ts      # Framework-agnostic class
+│   │   ├── useAvatarController.ts   # React hook wrapper
+│   │   ├── emotions.ts      # Emotion-to-action mapping
+│   │   └── index.ts         # Public API
+│   │
+│   └── scripting/           # Scripting engine
+│       ├── parser/
+│       │   ├── Lexer.ts     # Tokenizer
+│       │   └── Parser.ts    # Script parser
+│       ├── ast/
+│       │   └── nodes.ts     # AST definitions
+│       ├── executor/
+│       │   └── ScriptExecutor.ts  # Script runner
+│       └── index.ts         # Public exports
+│
+├── components/
+│   ├── Avatar.tsx           # Visual renderer
+│   ├── AvatarControlPanel.tsx  # Control UI
+│   └── ScriptEditor.tsx     # Script input UI
+│
+├── examples/
+│   └── scripts.ts           # Example scripts
+│
+└── hooks/                   # Custom React hooks
+```
+
+### Key Design Principles
+
+1. **Framework-Agnostic Core**: The `AvatarController` class works without React
+2. **Type Safety**: Full TypeScript support with strict typing
+3. **Event-Driven**: Uses EventEmitter for reactive updates
+4. **Modular**: Each component has a single responsibility
+5. **Extensible**: Easy to add new expressions, sequences, or commands
+
+## Customization
+
+### Adding a New Expression
+
+Edit `src/lib/avatar/expressions.ts`:
+
+```typescript
+myExpression: {
+  id: "myExpression",
+  name: "My Expression",
+  state: {
+    eyes: { scaleY: 1, scaleX: 1, position: { x: 0, y: 0 } },
+    mouth: { shape: 'smile', openness: 0.6 },
+  },
+  transitionDuration: 150,
+  easing: "ease-out",
+}
+```
+
+### Creating an Animation Sequence
+
+Edit `src/lib/avatar/sequences.ts`:
+
+```typescript
+mySequence: {
+  id: "mySequence",
+  name: "My Sequence",
+  frames: [
+    { expression: "neutral", duration: 500 },
+    { expression: "happy", duration: 1000 },
+    { expression: "neutral", duration: 500 },
+  ],
+}
+```
+
+### Adjusting Eye Tracking
+
+Edit `src/hooks/useCursorTracking.ts`:
+
+- `DEAD_ZONE_RADIUS`: Center area with no movement (default: 0.08)
+- `SMOOTHING_FACTOR`: Motion smoothness 0-1 (default: 0.12)
+- `MAX_OFFSET`: Maximum eye displacement (default: 0.4)
+
+## Roadmap
+
+### MVP (Current - v0.1)
+- ✅ Framework-agnostic core controller
+- ✅ Rich mouth shapes (phonemes)
+- ✅ Scripting language (parser + executor)
+- ✅ React integration
+- ✅ Example scripts and documentation
+
+### Planned Features (v0.2+)
+- 🔜 **TTS Integration** - Web Speech API, ElevenLabs support
+- 🔜 **Lip-sync Engine** - Automatic phoneme matching
+- 🔜 **Audio Analysis** - Real-time audio-driven animation
+- 🔜 **Expression Blending** - Smooth interpolation between states
+- 🔜 **Vue/Svelte Adapters** - Framework-specific wrappers
+- 🔜 **NPM Package** - Easy installation via npm
+- 🔜 **Plugin System** - Custom commands and behaviors
+- 🔜 **Animation Timeline** - Visual sequence editor
+
+## Technologies Used
+
+This project is built with:
+
+- **React 18.3.1** - UI framework
+- **TypeScript 5.8.3** - Type safety
+- **Vite 5.4.19** - Build tool
+- **Tailwind CSS** - Styling
+- **shadcn/ui** - UI components
+- **TanStack React Query** - State management
+
+## Development
+
+### Available Scripts
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Dev server on http://localhost:8080 |
+| `npm run build` | Production build |
+| `npm run lint` | ESLint check |
+| `npm run preview` | Preview production build |
+| `npm run test` | Run tests once |
+| `npm run test:watch` | Tests in watch mode |
+
+### Path Aliases
+
+Use `@/` to reference `src/`:
+
+```typescript
+import { Avatar } from "@/components/Avatar";
+import { useAvatarController } from "@/lib/avatar";
+```
+
+## Deployment
+
+Build files go to `dist/` after `npm run build`. Deploy to:
+- Vercel
+- Netlify
+- GitHub Pages
+- Any static hosting
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+MIT License - feel free to use in your projects!
+
+## Support
+
+- **Documentation**: See `/CLAUDE.md` for detailed development guide
+- **Issues**: Report bugs or request features on GitHub
+- **Examples**: Check `src/examples/scripts.ts` for usage examples
+
+## Credits
+
+Built with ❤️ for the AI community.
+
+Special thanks to:
+- shadcn for the beautiful UI components
+- The React and TypeScript communities
+
+---
+
+**Ready to bring your AI to life with expressive avatars!** 🎭✨