@anam-ai/agent-widget 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,205 @@
+# @anam-ai/agent-widget
+
+Embeddable video agent widget for [Anam AI](https://anam.ai). Add a conversational AI avatar to any website with a single HTML snippet.
+
+## Quick Start
+
+Add two lines to your HTML:
+
+```html
+<anam-agent agent-id="your-persona-id"></anam-agent>
+<script src="https://unpkg.com/@anam-ai/agent-widget" async></script>
+```
+
+The widget auto-registers the `<anam-agent>` custom element on load. No build step required.
+
+> **Allowed origins:** Your persona must have an allowed origin configured in [Anam Lab](https://lab.anam.ai) widget settings for the domain you're embedding on, or "Allow everywhere" must be enabled. Without this, the widget will be blocked by default.
+
+## Installation
+
+### CDN (recommended for embedding)
+
+```html
+<script src="https://unpkg.com/@anam-ai/agent-widget" async></script>
+```
+
+Also available via jsDelivr:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@anam-ai/agent-widget" async></script>
+```
+
+### npm (for bundlers)
+
+```bash
+npm install @anam-ai/agent-widget
+```
+
+```typescript
+import { registerWidget } from '@anam-ai/agent-widget';
+
+registerWidget(); // registers <anam-agent>
+registerWidget('my-agent'); // or use a custom tag name
+```
+
+## Attributes
+
+Configure the widget entirely via HTML attributes. All are optional except `agent-id`.
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `agent-id` | string | — | Persona ID from Anam Lab. Required for streaming. |
+| `session-token` | string | — | Pre-created session token. Skips the `/v1/auth/widget` call when set (used by Lab preview). |
+| `api-base-url` | string | `https://api.anam.ai` | API endpoint override. |
+| `layout` | `inline` \| `floating` | `floating` | Inline renders in-flow; floating overlays the page. |
+| `initial-state` | `minimized` \| `expanded` | `expanded` | Floating layout only. Start as orb or expanded sheet. |
+| `position` | string | `bottom-right` | Corner preset (`bottom-right`, `bottom-left`, `top-right`, `top-left`) or custom bracket syntax. |
+| `ui-mute-button` | `true` \| `false` | `true` | Show microphone mute toggle. |
+| `ui-text-input` | `true` \| `false` | `true` | Show text message input. |
+| `ui-captions` | `true` \| `false` | `false` | Show conversation captions. |
+| `call-to-action` | string | `Talk to our assistant` | Text on the start button. |
+| `avatar-url` | string | — | Override avatar thumbnail image URL. |
+| `avatar-video-url` | string | — | Override avatar preview video URL. |
+| `agent-name` | string | — | Override persona name displayed in the CTA. |
+
+### Custom Positioning
+
+Beyond the four corner presets, use bracket syntax for pixel-level control:
+
+```html
+<anam-agent agent-id="..." position="[top-20,right-0]"></anam-agent>
+<anam-agent agent-id="..." position="[bottom-100,left-40]"></anam-agent>
+```
+
+## Layout Modes
+
+### Floating (default)
+
+Renders as a fixed-position overlay. Starts expanded or as a clickable orb depending on `initial-state`.
+
+```html
+<anam-agent
+  agent-id="your-persona-id"
+  layout="floating"
+  initial-state="minimized"
+  position="bottom-right"
+></anam-agent>
+```
+
+### Inline
+
+Renders in the normal document flow, filling its parent container.
+
+```html
+<div style="width: 400px; height: 600px;">
+  <anam-agent agent-id="your-persona-id" layout="inline"></anam-agent>
+</div>
+```
+
+## Configuration Priority
+
+The widget merges configuration from three sources (highest priority wins):
+
+1. **HTML attributes** — per-instance overrides set by the embedder
+2. **Server config** — persona settings from Anam Lab (fetched via API)
+3. **Widget defaults** — built-in fallbacks
+
+## How It Works
+
+1. **On load:** The widget fetches persona metadata (avatar image, name, display config) from `GET /v1/personas/:id/widget`
+2. **On user click:** Requests a session token from `POST /v1/auth/widget`, then starts a WebRTC stream via the Anam JS SDK
+3. **During session:** Real-time video avatar with voice input, optional text input, and mute controls
+4. **On close:** Stops the stream and cleans up resources
+
+## Events
+
+The widget dispatches custom DOM events on the `<anam-agent>` element:
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `anam-agent:session-started` | `{ sessionId }` | Stream connected |
+| `anam-agent:session-ended` | `{ sessionId, reason }` | Stream ended |
+| `anam-agent:message-received` | `{ role, content }` | Message from user or assistant |
+| `anam-agent:message-sent` | `{ content }` | Text message sent |
+| `anam-agent:expanded` | `{}` | Widget expanded from orb |
+| `anam-agent:collapsed` | `{}` | Widget collapsed to orb |
+| `anam-agent:error` | `{ code, message }` | Error occurred |
+| `anam-agent:mic-muted` | `{}` | Microphone muted |
+| `anam-agent:mic-unmuted` | `{}` | Microphone unmuted |
+
+```javascript
+document.querySelector('anam-agent').addEventListener('anam-agent:session-started', (e) => {
+  console.log('Session started:', e.detail.sessionId);
+});
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm 10+
+
+### Setup
+
+```bash
+pnpm install
+```
+
+### Dev Server
+
+```bash
+pnpm dev
+```
+
+Opens the playground at `http://localhost:5173/playground/` with HMR. The playground provides a sidebar with controls for all widget attributes and a live preview area.
+
+Set `VITE_ANAM_AGENT_ID` in `.env` to pre-fill the agent ID input.
+
+### Build
+
+```bash
+pnpm build
+```
+
+Outputs dual-format bundles to `dist/`:
+- `dist/index.js` — ESM (for bundlers)
+- `dist/index.umd.js` — UMD (for script tags)
+
+All dependencies are bundled into the output (zero runtime externals).
+
+### Preview Production Build
+
+```bash
+pnpm preview
+```
+
+Builds and serves at `http://localhost:4173/playground/preview.html` using the UMD bundle.
+
+### Type Check
+
+```bash
+pnpm typecheck
+```
+
+### Lint
+
+```bash
+pnpm lint
+```
+
+## Architecture
+
+- **Preact** — lightweight UI rendering (~4KB)
+- **Preact Signals** — fine-grained reactive state for session lifecycle
+- **Shadow DOM** — full CSS isolation from host page styles
+- **Web Components** — `<anam-agent>` custom element via `preact-custom-element`
+- **Tailwind CSS** — compiled and inlined into the Shadow DOM (no external stylesheets)
+- **Vite** — library-mode build with esbuild minification
+
+## Browser Support
+
+Modern browsers with Web Components and WebRTC support:
+- Chrome / Edge 80+
+- Firefox 63+
+- Safari 13.1+