@keyframelabs/elements 0.3.0 → 0.5.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,9 +70,96 @@ 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.
+Supports ElevenLabs, OpenAI Realtime, and KFL Voice Agent.
 
 For `PersonaEmbed`, this is determined by the values you set in the Keyframe platform dashboard.
 
@@ -184,10 +272,10 @@ type SessionDetails = {
 };
 
 type VoiceAgentDetails = {
-  type: 'elevenlabs' | 'openai';
+  type: 'elevenlabs' | 'openai' | 'kfl';
   token?: string;        // For openai (ephemeral client secret)
   agent_id?: string;     // For elevenlabs
-  signed_url?: string;   // For elevenlabs
+  signed_url?: string;   // For elevenlabs/kfl
   system_prompt?: string; // For openai
   voice?: string;         // For openai
 };

package/dist/KflEmbedElement.d.ts

@@ -0,0 +1,77 @@
+/**
+ * <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" | "call-to-action")[];
+    private shadow;
+    private embed;
+    private _widgetState;
+    private _connected;
+    private _connecting;
+    private _initialized;
+    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;
+    private readonly _onJoinClick;
+    private readonly _onEndCallClick;
+    private readonly _onMicClick;
+    private readonly _onToggleClick;
+    private readonly _onRevealClick;
+    private readonly _onInnerClick;
+    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 _initDom;
+    private _requireElement;
+    private _resolveInitialState;
+    private _renderJoinLabel;
+    private _applyPreviewImage;
+    private _readRenderConfig;
+    private _getAttrNum;
+    private _getCorner;
+    private _applyLayout;
+    private _applyState;
+    private _renderJoinButton;
+    private _renderToolbar;
+    private _renderToggleButton;
+    private _renderRevealButton;
+    private _renderJoinButtonColor;
+    private _shouldShowMinimizeButton;
+    private _handleJoinCall;
+    private _handleToggle;
+    private _handleInnerClick;
+    private _handleEndCall;
+    private _handleReveal;
+    private _setWidgetState;
+    private _handleMicToggle;
+    private _updateMicIcon;
+    private _hasLiveSession;
+    private _disconnectSession;
+    private _resetToMinimized;
+    private _showError;
+    private _connect;
+}

package/dist/agents/audio-utils.d.ts

@@ -28,3 +28,8 @@ export declare function createEventEmitter<T extends Record<string, any>>(): {
     removeAllListeners(): void;
 };
 export declare function floatTo16BitPCM(float32: Float32Array): Uint8Array;
+/**
+ * Create an AudioWorkletNode that captures mono PCM input and posts
+ * Float32Array chunks (1024 samples = 64ms at 16kHz) to its message port.
+ */
+export declare function createPcmWorkletNode(ctx: AudioContext): Promise<AudioWorkletNode>;

package/dist/agents/index.d.ts

@@ -1,5 +1,6 @@
 import { ElevenLabsAgent, ElevenLabsConfig } from './elevenlabs';
 import { OpenAIRealtimeAgent, OpenAIRealtimeConfig, TurnDetection } from './openai-realtime';
+import { KflAgent, KflAgentConfig } from './kfl';
 /**
  * Agent implementations for voice AI platforms.
  *
@@ -10,9 +11,10 @@ export { BaseAgent, DEFAULT_INPUT_SAMPLE_RATE } from './base';
 export type { Agent, AgentConfig, AgentEventMap, AgentState, Emotion } from './types';
 export { ElevenLabsAgent, type ElevenLabsConfig };
 export { OpenAIRealtimeAgent, type OpenAIRealtimeConfig, type TurnDetection };
-export { SAMPLE_RATE, base64ToBytes, bytesToBase64, resamplePcm, createEventEmitter, floatTo16BitPCM } from './audio-utils';
+export { KflAgent, type KflAgentConfig };
+export { SAMPLE_RATE, base64ToBytes, bytesToBase64, resamplePcm, createEventEmitter, floatTo16BitPCM, createPcmWorkletNode } from './audio-utils';
 /** Supported agent types */
-export type AgentType = 'elevenlabs' | 'openai';
+export type AgentType = 'elevenlabs' | 'openai' | 'kfl';
 /** Agent type metadata */
 export interface AgentTypeInfo {
     id: AgentType;
@@ -25,9 +27,10 @@ export declare const AGENT_REGISTRY: AgentTypeInfo[];
 export interface AgentConfigMap {
     elevenlabs: ElevenLabsConfig;
     openai: OpenAIRealtimeConfig;
+    kfl: KflAgentConfig;
 }
 /** Union type of all agent instances */
-export type AnyAgent = ElevenLabsAgent | OpenAIRealtimeAgent;
+export type AnyAgent = ElevenLabsAgent | OpenAIRealtimeAgent | KflAgent;
 /**
  * Create an agent instance by type.
  *
@@ -39,6 +42,7 @@ export type AnyAgent = ElevenLabsAgent | OpenAIRealtimeAgent;
  */
 export declare function createAgent(type: 'elevenlabs'): ElevenLabsAgent;
 export declare function createAgent(type: 'openai'): OpenAIRealtimeAgent;
+export declare function createAgent(type: 'kfl'): KflAgent;
 export declare function createAgent(type: AgentType): AnyAgent;
 /**
  * Get agent type metadata by ID.

package/dist/agents/kfl.d.ts

@@ -0,0 +1,26 @@
+import { AgentConfig } from './types';
+import { BaseAgent } from './base';
+export interface KflAgentConfig extends AgentConfig {
+    /** WebSocket endpoint for kfl-voice-agent (wss://.../ws) */
+    wsUrl: string;
+    /** Optional ping interval override (ms) */
+    pingIntervalMs?: number;
+}
+export declare class KflAgent extends BaseAgent {
+    protected readonly agentName = "KflVoiceAgent";
+    private connectResolve;
+    private connectReject;
+    private connectTimeout;
+    private pingInterval;
+    private sourceInputSampleRate;
+    private turnEnded;
+    connect(config: KflAgentConfig): Promise<void>;
+    sendAudio(pcmData: Uint8Array): void;
+    close(): void;
+    protected handleParsedMessage(message: unknown): void;
+    private startPings;
+    private stopPings;
+    private clearConnectTimeout;
+    private resolvePendingConnect;
+    private rejectPendingConnect;
+}

package/dist/index.d.ts

@@ -3,9 +3,10 @@ export type { PersonaEmbedOptions } from './PersonaEmbed';
 export { PersonaView } from './PersonaView';
 export type { PersonaViewOptions } from './PersonaView';
 export type { EmbedStatus, VideoFit, VoiceAgentDetails, SessionDetails, BaseCallbacks, } from './types';
-export { createAgent, ElevenLabsAgent, OpenAIRealtimeAgent, BaseAgent, AGENT_REGISTRY, getAgentInfo, } from './agents';
-export type { AgentType, AgentConfig, AgentEventMap, Agent, AnyAgent, AgentTypeInfo, ElevenLabsConfig, OpenAIRealtimeConfig, TurnDetection, } from './agents';
+export { createAgent, ElevenLabsAgent, OpenAIRealtimeAgent, KflAgent, BaseAgent, AGENT_REGISTRY, getAgentInfo, } from './agents';
+export type { AgentType, AgentConfig, AgentEventMap, Agent, AnyAgent, AgentTypeInfo, ElevenLabsConfig, OpenAIRealtimeConfig, KflAgentConfig, 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';