@keyframelabs/elements 0.3.0 → 0.4.0

package/README.md

@@ -18,9 +18,10 @@ pnpm add @keyframelabs/elements
 
 ## Usage
 
-This package provides two primary classes depending on your integration strategy:
+This package provides three integration options depending on your strategy:
 1. **`PersonaEmbed`**: Fully managed. Uses a publishable key. Best for rapid frontend integration.
 2. **`PersonaView`**: Bring your own backend. Uses session tokens generated by your server.
+3. **`<kfl-embed>`**: Drop-in web component. Wraps `PersonaEmbed` with a complete widget UI (states, controls, positioning). Zero framework dependencies.
 
 ### Option A: PersonaEmbed (managed)
 
@@ -69,6 +70,93 @@ await view.connect();
 view.disconnect();
 ```
 
+### Option C: `<kfl-embed>` Web Component
+
+A self-registering custom element that wraps `PersonaEmbed` with a widget UI shell: minimized/active/hidden states, "Join call" button, minimize/expand toggle, corner positioning, and button color styling. Drop it into any page with zero framework dependencies.
+
+```html
+<kfl-embed
+  publishable-key="kfl_pk_live_..."
+  initial-state="minimized"
+  corner="bottom-right"
+  minimized-width="144"
+  minimized-height="216"
+  active-width="252"
+  active-height="377"
+  button-color="#919191"
+  button-color-opacity="0.3"
+  video-fit="cover"
+  preview-image="https://example.com/avatar.png"></kfl-embed>
+<script type="module" src="https://unpkg.com/@keyframelabs/elements/dist/kfl-embed.js"></script>
+```
+
+#### Attributes
+
+| Attribute                        | Type                                                       | Default          | Description                                                        |
+| -------------------------------- | ---------------------------------------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `publishable-key`                | `string`                                                   | Required         | Your publishable embed key.                                        |
+| `api-base-url`                   | `string`                                                   | Keyframe default | Base URL for the Keyframe API.                                     |
+| `initial-state`                  | `'minimized' \| 'active' \| 'hidden'`                      | `'minimized'`    | Widget state on first load.                                        |
+| `controlled-widget-state`        | `'minimized' \| 'active' \| 'hidden'`                      | —                | Externally control the widget state (overrides internal state).     |
+| `corner`                         | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Which corner to anchor the widget (fixed mode only).               |
+| `inline`                         | boolean attribute                                          | —                | Use `position: relative` instead of `fixed`.                       |
+| `minimized-width`                | `number`                                                   | `144`            | Width in px when minimized.                                        |
+| `minimized-height`               | `number`                                                   | `216`            | Height in px when minimized.                                       |
+| `active-width`                   | `number`                                                   | `252`            | Width in px when active (in-call).                                 |
+| `active-height`                  | `number`                                                   | `377`            | Height in px when active (in-call).                                |
+| `hide-ui`                        | boolean attribute                                          | —                | Hides all overlay controls. Useful for building your own UI shell. |
+| `show-minimize-button`           | `'true' \| 'false'`                                        | `'true'`         | Show the X/minimize button on hover.                               |
+| `controlled-show-minimize-button`| `'true' \| 'false'`                                        | —                | Externally control the minimize button visibility.                 |
+| `button-color`                   | hex color string                                           | `'#919191'`      | Color of the "Join call" button.                                   |
+| `button-color-opacity`           | `number` (0–1)                                             | `0.3`            | Opacity of the "Join call" button background.                      |
+| `video-fit`                      | `'cover' \| 'contain'`                                     | `'cover'`        | Video scaling mode.                                                |
+| `preview-image`                  | URL string                                                 | —                | Image shown in the widget before a call starts.                    |
+
+#### Events
+
+| Event              | `detail`                                | Description                            |
+| ------------------ | --------------------------------------- | -------------------------------------- |
+| `statechange`      | `{ status: EmbedStatus }`               | Connection status changed.             |
+| `agentstatechange` | `{ state: AgentState }`                 | Avatar playback state changed.         |
+| `widgetstatechange`| `{ state: 'minimized' \| 'active' \| 'hidden' }` | Widget UI state changed.      |
+| `disconnected`     | —                                       | Session disconnected.                  |
+| `error`            | `{ error: Error }`                      | A fatal error occurred.                |
+
+#### JavaScript API
+
+```ts
+const el = document.querySelector('kfl-embed');
+
+await el.micOn();     // Start session if needed, then unmute mic
+await el.micOff();    // Mute mic
+el.isMicOn();         // boolean
+
+await el.mute();      // Mute speaker audio
+await el.unmute();    // Unmute speaker audio
+el.isMuted();         // boolean
+```
+
+#### Build
+
+The web component is built as a self-contained ES module via `vite.config.embed.ts`:
+
+```bash
+pnpm build:embed   # → dist/kfl-embed.js
+```
+
+Import the auto-registering entry point (registers `<kfl-embed>` on `customElements`):
+
+```ts
+import '@keyframelabs/elements/kfl-embed';
+```
+
+Or import the class directly for manual registration:
+
+```ts
+import { KflEmbedElement } from '@keyframelabs/elements';
+customElements.define('my-embed', KflEmbedElement);
+```
+
 ## Supported agents and real-time LLMs
 
 Supports ElevenLabs and OpenAI Realtime.

package/dist/KflEmbedElement.d.ts

@@ -0,0 +1,55 @@
+/**
+ * <kfl-embed> Web Component
+ *
+ * Composes PersonaEmbed internally -- does NOT reimplement session/video/audio logic.
+ * Adds the widget UI shell: minimized/active/hidden states, "Join call" button,
+ * minimize/expand toggle, corner positioning CSS, button color styling.
+ */
+export declare class KflEmbedElement extends HTMLElement {
+    static get observedAttributes(): ("publishable-key" | "api-base-url" | "initial-state" | "controlled-widget-state" | "active-width" | "active-height" | "minimized-width" | "minimized-height" | "inline" | "corner" | "hide-ui" | "show-minimize-button" | "controlled-show-minimize-button" | "button-color" | "button-color-opacity" | "video-fit" | "preview-image")[];
+    private shadow;
+    private embed;
+    private _widgetState;
+    private _connected;
+    private _connecting;
+    private widgetEl;
+    private innerEl;
+    private containerEl;
+    private previewImg;
+    private spinnerEl;
+    private errorToast;
+    private errorTimer;
+    private joinBtn;
+    private endCallBtn;
+    private toggleBtn;
+    private revealBtn;
+    private toolbarEl;
+    private micBtn;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    mute(): Promise<void>;
+    unmute(): Promise<void>;
+    isMuted(): boolean;
+    canUnmute(): boolean;
+    micOn(): Promise<void>;
+    micOff(): Promise<void>;
+    isMicOn(): boolean;
+    canTurnOnMic(): boolean;
+    setEmotion(_emotion: 'neutral' | 'angry' | 'sad' | 'happy'): void;
+    private _getAttrNum;
+    private _getCorner;
+    private _applyLayout;
+    private _applyState;
+    private _shouldShowMinimizeButton;
+    private _handleJoinCall;
+    private _handleToggle;
+    private _handleEndCall;
+    private _handleReveal;
+    private _handleMicToggle;
+    private _updateMicIcon;
+    private _resetToMinimized;
+    private _showError;
+    private _connect;
+}

package/dist/index.d.ts

@@ -7,5 +7,6 @@ export { createAgent, ElevenLabsAgent, OpenAIRealtimeAgent, BaseAgent, AGENT_REG
 export type { AgentType, AgentConfig, AgentEventMap, Agent, AnyAgent, AgentTypeInfo, ElevenLabsConfig, OpenAIRealtimeConfig, TurnDetection, } from './agents';
 export type { AgentState } from '@keyframelabs/sdk';
 export { floatTo16BitPCM, resamplePcm, base64ToBytes, bytesToBase64, SAMPLE_RATE, createEventEmitter, } from './agents';
+export { KflEmbedElement } from './KflEmbedElement';
 export { ApiError as KeyframeApiError } from './ApiError';
 export type { ApiErrorPayload as KeyframeApiErrorPayload } from './ApiError';