@lokutor/sdk 1.1.17 → 1.1.20

package/dist/index.mjs

@@ -1,9 +1,75 @@
-import {
-  AUDIO_CONFIG,
-  DEFAULT_URLS,
-  Language,
-  VoiceStyle
-} from "./chunk-UI24THO7.mjs";
+// src/types.ts
+var VoiceStyle = /* @__PURE__ */ ((VoiceStyle2) => {
+  VoiceStyle2["F1"] = "F1";
+  VoiceStyle2["F2"] = "F2";
+  VoiceStyle2["F3"] = "F3";
+  VoiceStyle2["F4"] = "F4";
+  VoiceStyle2["F5"] = "F5";
+  VoiceStyle2["M1"] = "M1";
+  VoiceStyle2["M2"] = "M2";
+  VoiceStyle2["M3"] = "M3";
+  VoiceStyle2["M4"] = "M4";
+  VoiceStyle2["M5"] = "M5";
+  return VoiceStyle2;
+})(VoiceStyle || {});
+var Language = /* @__PURE__ */ ((Language2) => {
+  Language2["ENGLISH"] = "en";
+  Language2["SPANISH"] = "es";
+  Language2["FRENCH"] = "fr";
+  Language2["PORTUGUESE"] = "pt";
+  Language2["KOREAN"] = "ko";
+  return Language2;
+})(Language || {});
+var AUDIO_CONFIG = {
+  SAMPLE_RATE: 16e3,
+  SAMPLE_RATE_INPUT: 16e3,
+  SPEAKER_SAMPLE_RATE: 44100,
+  SAMPLE_RATE_OUTPUT: 44100,
+  CHANNELS: 1,
+  CHUNK_DURATION_MS: 20,
+  get CHUNK_SIZE() {
+    return Math.floor(this.SAMPLE_RATE * this.CHUNK_DURATION_MS / 1e3);
+  }
+};
+var DEFAULT_URLS = {
+  VOICE_AGENT: "wss://api.lokutor.com/ws/agent",
+  TTS: "wss://api.lokutor.com/ws/tts"
+};
+var LokutorError = class extends Error {
+  code;
+  detail;
+  retryable;
+  original;
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "LokutorError";
+    this.code = code;
+    this.detail = opts?.detail;
+    this.retryable = opts?.retryable ?? isRetryableCode(code);
+    this.original = opts?.original;
+  }
+};
+function isRetryableCode(code) {
+  const fatal = [
+    "auth.missing_key",
+    "auth.invalid_key",
+    "auth.time_limited",
+    "validation.invalid_voice",
+    "validation.invalid_language",
+    "validation.text_too_long",
+    "validation.speed_out_of_range",
+    "validation.steps_out_of_range",
+    "validation.invalid_request_format",
+    "internal.cancelled"
+  ];
+  return !fatal.includes(code);
+}
+function isRetryable(error) {
+  if (error instanceof LokutorError) {
+    return error.retryable;
+  }
+  return false;
+}
 
 // src/audio-utils.ts
 function pcm16ToFloat32(int16Data) {
@@ -64,6 +130,9 @@ function pcm16ToBytes(data) {
   return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
 }
 function bytesToPcm16(bytes) {
+  if (bytes.length % 2 !== 0) {
+    bytes = bytes.slice(0, bytes.length - 1);
+  }
   return new Int16Array(bytes.buffer, bytes.byteOffset, bytes.length / 2);
 }
 function normalizeAudio(data, targetPeak = 0.95) {
@@ -113,11 +182,14 @@ var StreamResampler = class {
     combined.set(this.inputBuffer);
     combined.set(inputChunk, this.inputBuffer.length);
     const ratio = this.inputRate / this.outputRate;
-    const outputLength = Math.floor(combined.length / ratio);
+    let outputLength = Math.floor(combined.length / ratio);
     if (outputLength === 0 && !flush) {
       this.inputBuffer = combined;
       return new Float32Array(0);
     }
+    if (flush && outputLength === 0 && combined.length > 0) {
+      outputLength = 1;
+    }
     const output = new Float32Array(outputLength);
     for (let i = 0; i < outputLength; i++) {
       const pos = i * ratio;
@@ -126,10 +198,8 @@ var StreamResampler = class {
       const weight = pos - left;
       output[i] = combined[left] * (1 - weight) + combined[right] * weight;
     }
-    const remainingSamples = Math.ceil(combined.length - outputLength * ratio);
-    this.inputBuffer = combined.slice(
-      combined.length - remainingSamples
-    );
+    const consumed = Math.floor(outputLength * ratio);
+    this.inputBuffer = combined.slice(consumed);
     return output;
   }
   reset() {
@@ -291,6 +361,10 @@ var BrowserAudioManager = class {
       console.warn("AudioContext not initialized");
       return;
     }
+    if (pcm16Data.length % 2 !== 0) {
+      console.warn(`Discarding odd-length PCM buffer (${pcm16Data.length} bytes)`);
+      return;
+    }
     const int16Array = new Int16Array(
       pcm16Data.buffer,
       pcm16Data.byteOffset,
@@ -419,6 +493,54 @@ var BrowserAudioManager = class {
 };
 
 // src/client.ts
+function sdkTraceEnabled() {
+  try {
+    if (typeof window === "undefined") return false;
+    const w = window;
+    return Boolean(w.LOKUTOR_TRACE) || window.localStorage?.getItem("lokutorTrace") === "1";
+  } catch {
+    return false;
+  }
+}
+function sdkTrace(...args) {
+  if (sdkTraceEnabled()) {
+    console.log("[SDK TRACE]", ...args);
+  }
+}
+function nowMs() {
+  if (typeof performance !== "undefined" && performance.now) {
+    return performance.now();
+  }
+  return Date.now();
+}
+function wsToHttp(url) {
+  return url.replace(/^wss:/, "https:").replace(/^ws:/, "http:");
+}
+async function fetchJson(url, timeoutMs = 1e4) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      headers: { Accept: "application/json" }
+    });
+    clearTimeout(timer);
+    if (!res.ok) {
+      throw new LokutorError("internal.error", `HTTP ${res.status} from ${url}`, {
+        detail: await res.text().catch(() => ""),
+        retryable: res.status >= 500
+      });
+    }
+    return await res.json();
+  } catch (err) {
+    clearTimeout(timer);
+    if (err instanceof LokutorError) throw err;
+    throw new LokutorError("internal.error", `Failed to fetch ${url}`, {
+      original: err,
+      retryable: true
+    });
+  }
+}
 function base64ToUint8Array(base64) {
   const binaryString = atob(base64);
   const bytes = new Uint8Array(binaryString.length);
@@ -427,6 +549,39 @@ function base64ToUint8Array(base64) {
   }
   return bytes;
 }
+function normalizeVisemes(payload) {
+  if (!Array.isArray(payload)) return [];
+  const normalized = [];
+  for (const item of payload) {
+    if (!item || typeof item !== "object") continue;
+    const c = String(item.c ?? item.char ?? "sil").toLowerCase();
+    const t = Number(item.t ?? item.timestamp ?? 0);
+    const v = Number(item.v ?? item.id ?? 0);
+    normalized.push({
+      v: Number.isFinite(v) ? v : 0,
+      c,
+      t: Number.isFinite(t) ? t : 0
+    });
+  }
+  return normalized;
+}
+function extractVisemePayload(msg) {
+  if (Array.isArray(msg?.data)) {
+    return normalizeVisemes(msg.data);
+  }
+  if (Array.isArray(msg?.data?.visemes)) {
+    return normalizeVisemes(msg.data.visemes);
+  }
+  if (msg?.data && !Array.isArray(msg.data) && typeof msg.data === "object") {
+    const singularInData = normalizeVisemes([msg.data]);
+    if (singularInData.length > 0) return singularInData;
+  }
+  if (msg && !Array.isArray(msg) && typeof msg === "object") {
+    const singularAtRoot = normalizeVisemes([msg]);
+    if (singularAtRoot.length > 0) return singularAtRoot;
+  }
+  return [];
+}
 var VoiceAgentClient = class {
   ws = null;
   apiKey;
@@ -454,11 +609,13 @@ var VoiceAgentClient = class {
   reconnecting = false;
   reconnectAttempts = 0;
   maxReconnectAttempts = 5;
+  serverUrl;
   constructor(config) {
     this.apiKey = config.apiKey;
     this.prompt = config.prompt;
     this.voice = config.voice || "F1" /* F1 */;
     this.language = config.language || "en" /* ENGLISH */;
+    this.serverUrl = config.serverUrl || DEFAULT_URLS.VOICE_AGENT;
     this.onTranscription = config.onTranscription;
     this.onResponse = config.onResponse;
     this.onAudioCallback = config.onAudio;
@@ -486,13 +643,28 @@ var VoiceAgentClient = class {
       }
     }
     return new Promise((resolve, reject) => {
+      let settled = false;
+      const settle = (fn) => {
+        if (!settled) {
+          settled = true;
+          fn();
+        }
+      };
       try {
-        let url = DEFAULT_URLS.VOICE_AGENT;
+        let url = this.serverUrl;
         if (this.apiKey) {
           const separator = url.includes("?") ? "&" : "?";
           url += `${separator}api_key=${this.apiKey}`;
         }
-        console.log(`\u{1F517} Connecting to ${DEFAULT_URLS.VOICE_AGENT}...`);
+        const redactedUrl = url.replace(/api_key=[^&]+/, "api_key=***");
+        sdkTrace("ws.connect", {
+          endpoint: this.serverUrl,
+          url: redactedUrl,
+          enableAudio: this.enableAudio,
+          wantVisemes: this.wantVisemes,
+          hasAudioManager: Boolean(this.audioManager)
+        });
+        console.log(`\u{1F517} Connecting to ${this.serverUrl}...`);
         this.ws = new WebSocket(url);
         this.ws.binaryType = "arraybuffer";
         this.ws.onopen = async () => {
@@ -500,6 +672,7 @@ var VoiceAgentClient = class {
           this.reconnectAttempts = 0;
           this.reconnecting = false;
           console.log("\u2705 Connected to voice agent!");
+          sdkTrace("ws.open");
           this.sendConfig();
           if (this.audioManager) {
             await this.audioManager.startMicrophone((data) => {
@@ -508,22 +681,54 @@ var VoiceAgentClient = class {
               }
             });
           }
-          resolve(true);
+          settle(() => resolve(true));
         };
         this.ws.onmessage = async (event) => {
           if (event.data instanceof ArrayBuffer) {
+            sdkTrace("ws.message.binary", { bytes: event.data.byteLength });
             this.handleBinaryMessage(new Uint8Array(event.data));
           } else {
+            sdkTrace("ws.message.text", { length: String(event.data).length });
             this.handleTextMessage(event.data.toString());
           }
         };
         this.ws.onerror = (err) => {
-          console.error("\u274C WebSocket error:", err);
-          if (this.onError) this.onError(err);
-          if (!this.isConnected) reject(err);
+          const error = new LokutorError("ws.close", "WebSocket connection error", {
+            detail: `readyState=${this.ws?.readyState}, bufferedAmount=${this.ws?.bufferedAmount}`,
+            original: err,
+            retryable: true
+          });
+          console.error("\u274C WebSocket error:", error.message);
+          sdkTrace("ws.error", { code: error.code, message: error.message });
+          if (this.onError) this.onError(error);
+          if (!this.isConnected) {
+            settle(() => reject(error));
+          }
         };
-        this.ws.onclose = () => {
+        this.ws.onclose = (event) => {
           this.isConnected = false;
+          const diagnostic = {
+            code: event.code,
+            reason: event.reason,
+            wasClean: event.wasClean,
+            url: this.serverUrl,
+            isUserDisconnect: this.isUserDisconnect,
+            reconnectAttempts: this.reconnectAttempts
+          };
+          sdkTrace("ws.close", diagnostic);
+          if (!settled && !this.isUserDisconnect) {
+            const error = new LokutorError("ws.close", `WebSocket closed unexpectedly (code ${event.code})`, {
+              detail: event.reason || "No reason provided",
+              retryable: event.code !== 1008
+            });
+            settle(() => reject(error));
+            return;
+          }
+          if (!event.wasClean && event.code === 1006 && this.reconnectAttempts === 0 && !this.isUserDisconnect) {
+            console.error("\u274C Connection rejected (code 1006). Likely causes: invalid API key, endpoint unavailable, or CORS blocked.");
+            console.error("   URL:", this.serverUrl.replace(/api_key=[^&]+/, "api_key=***"));
+          }
+          console.log(`\u{1F50C} WebSocket closed \u2014 code: ${event.code}, reason: "${event.reason || "none"}", clean: ${event.wasClean}`);
           if (!this.isUserDisconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
             this.reconnecting = true;
             this.reconnectAttempts++;
@@ -539,37 +744,27 @@ var VoiceAgentClient = class {
           }
         };
       } catch (err) {
-        if (this.onError) this.onError(err);
-        reject(err);
+        const error = err instanceof LokutorError ? err : new LokutorError("internal.error", "Failed to create WebSocket connection", { original: err });
+        if (this.onError) this.onError(error);
+        settle(() => reject(error));
       }
     });
   }
   /**
    * The "Golden Path" - Starts a managed session with hardware handled automatically.
-   * This is the recommended way to start a conversation in both Browser and Node.js.
+   * This is the recommended way to start a conversation in browser environments.
    */
   async startManaged(config) {
     this.enableAudio = true;
     if (config?.audioManager) {
       this.audioManager = config.audioManager;
     } else if (!this.audioManager) {
-      if (typeof window !== "undefined") {
-        this.audioManager = new BrowserAudioManager();
-      } else {
-        try {
-          const { NodeAudioManager } = await import("./node-audio-5HOWE6MC.mjs");
-          this.audioManager = new NodeAudioManager();
-        } catch (e) {
-          console.error('\u274C Failed to load NodeAudioManager. Please ensure "speaker" and "node-record-lpcm16" are installed.');
-        }
+      if (typeof window === "undefined") {
+        throw new LokutorError("internal.error", "startManaged() requires a browser environment. Pass a custom audioManager for non-browser runtimes.", { retryable: false });
       }
+      this.audioManager = new BrowserAudioManager();
     }
     await this.connect();
-    if (this.audioManager && this.isConnected) {
-      await this.audioManager.startMicrophone((data) => {
-        this.sendAudio(data);
-      });
-    }
     return this;
   }
   /**
@@ -577,10 +772,18 @@ var VoiceAgentClient = class {
    */
   sendConfig() {
     if (!this.ws || !this.isConnected) return;
-    this.ws.send(JSON.stringify({ type: "prompt", data: this.prompt }));
+    this.ws.send(JSON.stringify({ type: "visemes", data: this.wantVisemes }));
     this.ws.send(JSON.stringify({ type: "voice", data: this.voice }));
     this.ws.send(JSON.stringify({ type: "language", data: this.language }));
-    this.ws.send(JSON.stringify({ type: "visemes", data: this.wantVisemes }));
+    this.ws.send(JSON.stringify({ type: "prompt", data: this.prompt }));
+    this.ws.send(JSON.stringify({ type: "rates", playback: 44100, input: 16e3 }));
+    sdkTrace("ws.send.config", {
+      promptLen: this.prompt?.length || 0,
+      voice: this.voice,
+      language: this.language,
+      visemes: this.wantVisemes,
+      tools: this.tools?.length || 0
+    });
     if (this.tools && this.tools.length > 0) {
       this.ws.send(JSON.stringify({ type: "tools", data: this.tools }));
     }
@@ -614,6 +817,15 @@ var VoiceAgentClient = class {
   handleTextMessage(text) {
     try {
       const msg = JSON.parse(text);
+      if (!msg || typeof msg !== "object") {
+        return;
+      }
+      sdkTrace("ws.recv.type", {
+        type: msg.type,
+        hasData: Object.prototype.hasOwnProperty.call(msg, "data"),
+        dataKind: Array.isArray(msg.data) ? "array" : typeof msg.data,
+        generation: msg.generation ?? null
+      });
       switch (msg.type) {
         case "audio":
           if (msg.data) {
@@ -626,7 +838,7 @@ var VoiceAgentClient = class {
           this.messages.push({
             role,
             text: msg.data,
-            timestamp: Date.now()
+            timestamp: nowMs()
           });
           if (msg.role === "user") {
             if (this.onTranscription) this.onTranscription(msg.data);
@@ -658,19 +870,44 @@ var VoiceAgentClient = class {
           console.log(`${icons[msg.data] || ""} Status: ${msg.data}`);
           break;
         case "visemes":
-          if (Array.isArray(msg.data) && msg.data.length > 0) {
-            this.emit("visemes", msg.data);
+        case "viseme": {
+          const msgGen = msg.generation ?? this.currentGeneration;
+          if (msgGen < this.currentGeneration) {
+            sdkTrace("visemes.discard", { msgGen, currentGen: this.currentGeneration });
+            break;
+          }
+          const normalized = extractVisemePayload(msg);
+          const explicitlyEmptyArray = Array.isArray(msg?.data) || Array.isArray(msg?.data?.visemes);
+          sdkTrace("visemes.recv", {
+            rawType: msg.type,
+            normalizedCount: normalized.length,
+            first: normalized[0] ?? null
+          });
+          if (normalized.length > 0 || explicitlyEmptyArray) {
+            this.emit("visemes", normalized);
           }
           break;
-        case "error":
-          if (this.onError) this.onError(msg.data);
-          console.error(`\u274C Server error: ${msg.data}`);
+        }
+        case "error": {
+          const backendCode = msg.data?.code ?? "internal.error";
+          const backendMessage = msg.data?.message ?? msg.data ?? "Unknown server error";
+          const backendDetail = msg.data?.detail;
+          const backendRetryable = msg.data?.retryable ?? true;
+          const error = new LokutorError(backendCode, backendMessage, {
+            detail: backendDetail,
+            retryable: backendRetryable
+          });
+          if (this.onError) this.onError(error);
+          console.error(`\u274C Server error: [${error.code}] ${error.message}`);
           break;
+        }
         case "tool_call":
           console.log(`\u{1F6E0}\uFE0F Tool Call: ${msg.name}(${msg.arguments})`);
           break;
       }
     } catch (e) {
+      sdkTrace("ws.recv.parse_error", { preview: text?.slice(0, 120) });
+      console.debug("Failed to parse message:", e);
     }
   }
   /**
@@ -732,6 +969,21 @@ var VoiceAgentClient = class {
       this.audioManager.cleanup();
     }
     this.isConnected = false;
+    this.reconnecting = false;
+    this.reconnectAttempts = 0;
+  }
+  /**
+   * Returns true if the client is currently connected.
+   */
+  get connected() {
+    return this.isConnected;
+  }
+  /**
+   * Returns the current generation counter.
+   * Useful for correlating audio/viseme chunks with utterances.
+   */
+  get generation() {
+    return this.currentGeneration;
   }
   /**
    * Toggles the microphone mute state (if managed by client)
@@ -754,17 +1006,70 @@ var VoiceAgentClient = class {
     }
     return 0;
   }
+  /**
+   * Fetch available voice styles from the server.
+   * No authentication required.
+   */
+  static async fetchVoices(baseUrl) {
+    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const data = await fetchJson(`${url}/voices`);
+    return data.voices || [];
+  }
+  /**
+   * Fetch supported languages from the server.
+   * No authentication required.
+   */
+  static async fetchLanguages(baseUrl) {
+    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const data = await fetchJson(`${url}/languages`);
+    return data.languages || [];
+  }
+  /**
+   * Fetch loaded TTS model versions from the server.
+   * No authentication required.
+   */
+  static async fetchModels(baseUrl) {
+    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const data = await fetchJson(`${url}/models`);
+    return data.models || [];
+  }
+  /**
+   * Fetch server configuration (limits and defaults).
+   * No authentication required.
+   */
+  static async fetchConfig(baseUrl) {
+    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    return fetchJson(`${url}/config`);
+  }
+  /**
+   * Fetch rich runtime status from the server.
+   * No authentication required.
+   */
+  static async fetchStatus(baseUrl) {
+    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    return fetchJson(`${url}/status`);
+  }
+  /**
+   * Fetch health/liveness status from the server.
+   * No authentication required.
+   */
+  static async fetchHealth(baseUrl) {
+    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    return fetchJson(`${url}/health`);
+  }
   /**
    * Update the system prompt mid-conversation
    */
   updatePrompt(newPrompt) {
     this.prompt = newPrompt;
-    if (this.ws && this.isConnected) {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN && this.isConnected) {
       try {
         this.ws.send(JSON.stringify({ type: "prompt", data: newPrompt }));
         console.log(`\u2699\uFE0F Updated prompt: ${newPrompt.substring(0, 50)}...`);
       } catch (error) {
-        console.error("Error updating prompt:", error);
+        const err = new LokutorError("internal.error", "Failed to update prompt", { original: error });
+        if (this.onError) this.onError(err);
+        console.error("Error updating prompt:", err.message);
       }
     } else {
       console.warn("Not connected - prompt will be updated on next connection");
@@ -827,37 +1132,52 @@ var TTSClient = class {
             visemes: options.visemes || false
           };
           ws.send(JSON.stringify(req));
-          startTime = Date.now();
+          startTime = nowMs();
         };
         ws.onmessage = async (event) => {
           refreshTimeout();
           if (event.data instanceof ArrayBuffer) {
             if (!firstByteReceived) {
-              const ttfb = Date.now() - startTime;
+              const ttfb = nowMs() - startTime;
               if (options.onTTFB) options.onTTFB(ttfb);
               firstByteReceived = true;
             }
             if (options.onAudio) options.onAudio(new Uint8Array(event.data));
-          } else {
-            const text = event.data.toString();
-            if (text === "EOS") {
+            return;
+          }
+          const text = event.data.toString();
+          if (text === "EOS") {
+            if (activityTimeout) clearTimeout(activityTimeout);
+            ws.close();
+            resolve();
+            return;
+          }
+          try {
+            const msg = JSON.parse(text);
+            if (msg.type === "audio" && msg.data) {
+              const audioBuffer = base64ToUint8Array(msg.data);
+              if (!firstByteReceived) {
+                const ttfb = nowMs() - startTime;
+                if (options.onTTFB) options.onTTFB(ttfb);
+                firstByteReceived = true;
+              }
+              if (options.onAudio) options.onAudio(audioBuffer);
+              return;
+            }
+            if (msg.type === "visemes" && Array.isArray(msg.data) && options.onVisemes) {
+              options.onVisemes(normalizeVisemes(msg.data));
+              return;
+            }
+            if (Array.isArray(msg) && options.onVisemes) {
+              options.onVisemes(normalizeVisemes(msg));
+              return;
+            }
+            if (msg.type === "eos") {
               if (activityTimeout) clearTimeout(activityTimeout);
               ws.close();
               resolve();
-              return;
-            }
-            try {
-              const msg = JSON.parse(text);
-              if (Array.isArray(msg) && options.onVisemes) {
-                options.onVisemes(msg);
-              }
-              if (msg.type === "eos") {
-                if (activityTimeout) clearTimeout(activityTimeout);
-                ws.close();
-                resolve();
-              }
-            } catch (e) {
             }
+          } catch (e) {
           }
         };
         ws.onerror = (err) => {
@@ -886,11 +1206,587 @@ async function simpleTTS(options) {
   const client = new TTSClient({ apiKey: options.apiKey });
   return client.synthesize(options);
 }
+
+// src/conversational-panel.ts
+var PANEL_CSS = (
+  /*css*/
+  `
+  .cv-panel {
+    position: relative;
+    width: 100%;
+    aspect-ratio: 16 / 9;
+    max-height: 800px;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    padding: 2rem 0;
+    margin: 0;
+    background: var(--cv-bg, #0a0a0a);
+    box-shadow: inset 0 10px 40px rgba(0, 0, 0, 0.1), inset 0 0 100px rgba(0, 0, 0, 0.05);
+    border-radius: 40px;
+    overflow: hidden;
+    container-type: inline-size;
+  }
+  .cv-curtain {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    background: var(--cv-bg, #0a0a0a);
+    z-index: 100;
+    transition: transform 1s cubic-bezier(0.16, 1, 0.3, 1);
+  }
+  .cv-curtain .cv-curtain-bg {
+    position: absolute;
+    inset: 0;
+    background: url('/background_gradient.jpeg') center / cover no-repeat;
+    z-index: -1;
+  }
+  .cv-curtain .cv-curtain-overlay {
+    position: absolute;
+    inset: 0;
+    background: var(--cv-accent);
+    opacity: 0.35;
+    z-index: -1;
+  }
+  .cv-curtain.is-up { transform: translateY(-100%); }
+  .cv-curtain-content {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: clamp(0.75rem, 1.5cqi, 1.5rem);
+    color: #fff;
+    text-align: center;
+    z-index: 2;
+    padding: clamp(1rem, 2cqi, 2rem);
+  }
+  .cv-curtain-title {
+    font-size: clamp(1.2rem, 4cqi, 2.5rem);
+    font-weight: 800;
+    letter-spacing: -0.03em;
+    margin: 0;
+    text-shadow: 0 4px 20px rgba(0,0,0,0.3);
+  }
+  .cv-curtain-desc {
+    font-size: clamp(0.75rem, 2cqi, 1.1rem);
+    opacity: 0.8;
+    max-width: 400px;
+    margin: 0;
+    line-height: 1.5;
+  }
+  .cv-curtain-btn {
+    margin-top: 1rem;
+    padding: clamp(0.6rem, 1.5cqi, 1rem) clamp(1.5rem, 3cqi, 2.5rem);
+    border-radius: 100px;
+    background: #fff;
+    color: #000;
+    border: none;
+    font-weight: 700;
+    font-size: clamp(0.8rem, 1.5cqi, 1rem);
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    cursor: pointer;
+    transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+    box-shadow: 0 10px 30px rgba(0,0,0,0.2);
+  }
+  .cv-curtain-btn:hover {
+    transform: scale(1.05);
+    background: #f0f0f0;
+    box-shadow: 0 15px 40px rgba(0,0,0,0.3);
+  }
+  .cv-curtain-btn svg { transition: transform 0.3s ease; }
+  .cv-curtain-btn:hover svg { transform: translateX(4px); }
+  .cv-header {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.25rem;
+    z-index: 20;
+    margin-bottom: auto;
+  }
+  .cv-title {
+    font-size: clamp(1rem, 2.5cqi, 1.75rem);
+    font-weight: 700;
+    color: #e0e0e0;
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    letter-spacing: -0.02em;
+  }
+  .cv-title .cv-timer {
+    font-variant-numeric: tabular-nums;
+    color: var(--cv-accent);
+    font-weight: 400;
+    opacity: 0.8;
+  }
+  .cv-visualizer-wrap {
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    width: clamp(140px, 40cqi, 280px);
+    height: clamp(140px, 40cqi, 280px);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 10;
+    transition: all 0.5s cubic-bezier(0.16, 1, 0.3, 1);
+  }
+  .cv-is-speaking .cv-visualizer-wrap {
+    animation: cv-pulse 2.5s infinite ease-in-out;
+  }
+  .cv-is-thinking .cv-visualizer-wrap {
+    opacity: 0.5;
+    transform: translate(-50%, -50%) scale(0.9);
+  }
+  @keyframes cv-pulse {
+    0%, 100% { transform: translate(-50%, -50%) scale(1); }
+    50% { transform: translate(-50%, -50%) scale(1.05); }
+  }
+  .cv-canvas {
+    width: 100% !important;
+    height: 100% !important;
+    position: relative;
+    z-index: 0;
+  }
+  .cv-canvas {
+    width: 100% !important;
+    height: 100% !important;
+    position: relative;
+    z-index: 0;
+  }
+  .cv-controls {
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 1.5rem;
+    padding-top: 1rem;
+    margin-top: auto;
+    z-index: 20;
+  }
+  .cv-pill {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    background: rgba(255, 255, 255, 0.03);
+    backdrop-filter: blur(30px);
+    -webkit-backdrop-filter: blur(30px);
+    border: 1px solid rgba(255, 255, 255, 0.08);
+    padding: 0.3rem 0.75rem;
+    border-radius: 100px;
+    box-shadow: 0 20px 50px rgba(0, 0, 0, 0.3);
+  }
+  .cv-btn {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    background: transparent;
+    border: none;
+    color: rgba(255,255,255,0.55);
+    font-weight: 600;
+    font-size: 0.75rem;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    padding: 0.35rem 0.75rem;
+    border-radius: 50px;
+  }
+  .cv-btn:hover { color: #fff; background: rgba(255,255,255,0.05); }
+  .cv-btn--end { color: #ff4444; }
+  .cv-btn--end .cv-btn-box {
+    background: #ff4444;
+    width: 8px;
+    height: 8px;
+    border-radius: 2px;
+  }
+  .cv-btn.is-muted { color: var(--cv-accent); }
+  .cv-error {
+    position: absolute;
+    bottom: 1.25rem;
+    left: 50%;
+    transform: translateX(-50%);
+    background: #0a0a0a;
+    color: #e0e0e0;
+    padding: 0.75rem 1.5rem;
+    border-radius: 12px;
+    font-size: 0.875rem;
+    font-weight: 500;
+    display: none;
+    align-items: center;
+    gap: 0.75rem;
+    box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
+    z-index: 1000;
+    border: 1px solid rgba(255, 255, 255, 0.06);
+    backdrop-filter: blur(20px);
+  }
+  .cv-error.is-visible { display: flex; }
+  .cv-error-icon { color: var(--cv-accent); flex-shrink: 0; }
+`
+);
+var styleInjected = false;
+function injectStyles() {
+  if (styleInjected) return;
+  const style = document.createElement("style");
+  style.textContent = PANEL_CSS;
+  document.head.appendChild(style);
+  styleInjected = true;
+}
+var ConversationalPanel = class {
+  cfg;
+  container;
+  agent = null;
+  visualizer = null;
+  timerTicker = null;
+  connectingSound = null;
+  connectingFadeTimer = null;
+  isRunning = false;
+  // Cached DOM refs
+  el;
+  curtain;
+  curtainTitle;
+  curtainDesc;
+  startBtn;
+  errorEl;
+  errorText;
+  timerEl;
+  canvas;
+  muteBtn;
+  stopBtn;
+  visualizerWrap;
+  // Callbacks
+  onTranscription;
+  onResponse;
+  onStart;
+  onStop;
+  onError;
+  constructor(cfg) {
+    this.cfg = cfg;
+    this.container = cfg.container;
+    injectStyles();
+    this.buildDOM();
+  }
+  buildDOM() {
+    const accent = this.cfg.accentColor || "#a25a6b";
+    const bg = this.cfg.backgroundColor || "#0a0a0a";
+    this.container.style.setProperty("--cv-accent", accent);
+    this.container.style.setProperty("--cv-bg", bg);
+    this.el = document.createElement("div");
+    this.el.className = "cv-panel";
+    this.el.innerHTML = `
+      <div class="cv-curtain">
+        <div class="cv-curtain-bg"></div>
+        <div class="cv-curtain-overlay"></div>
+        <div class="cv-curtain-content">
+          <h3 class="cv-curtain-title">${this.esc(this.cfg.title)}</h3>
+          <p class="cv-curtain-desc">${this.esc(this.cfg.description)}</p>
+          <button class="cv-curtain-btn">
+            <span>Start Conversation</span>
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" width="20" height="20">
+              <path d="M5 12h14M12 5l7 7-7 7"/>
+            </svg>
+          </button>
+        </div>
+        <div class="cv-error">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+            width="20" height="20" class="cv-error-icon">
+            <circle cx="12" cy="12" r="10"></circle>
+            <path d="M12 8v4"></path>
+            <path d="M12 16h.01"></path>
+          </svg>
+          <span class="cv-error-text"></span>
+        </div>
+      </div>
+      <div class="cv-header">
+        <h2 class="cv-title">${this.esc(this.cfg.title)} <span class="cv-timer">00:00</span></h2>
+      </div>
+      <div class="cv-visualizer-wrap">
+        <canvas class="cv-canvas"></canvas>
+      </div>
+      <div class="cv-controls">
+        <div class="cv-pill">
+          <button class="cv-btn cv-btn--mute">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" width="18" height="18">
+              <path d="M12 1a3 3 0 0 0-3 3v8a3 3 0 0 0 6 0V4a3 3 0 0 0-3-3z"/>
+              <path d="M19 10v2a7 7 0 0 1-14 0v-2"/>
+            </svg>
+            <span>Mute</span>
+          </button>
+          <button class="cv-btn cv-btn--end">
+            <div class="cv-btn-box"></div>
+            <span>End call</span>
+          </button>
+        </div>
+      </div>
+    `;
+    this.container.appendChild(this.el);
+    this.curtain = this.el.querySelector(".cv-curtain");
+    if (this.cfg.curtainBgSrc) {
+      this.curtain.style.backgroundImage = `url('${this.cfg.curtainBgSrc}')`;
+    }
+    this.curtainTitle = this.el.querySelector(".cv-curtain-title");
+    this.curtainDesc = this.el.querySelector(".cv-curtain-desc");
+    this.startBtn = this.el.querySelector(".cv-curtain-btn");
+    this.errorEl = this.el.querySelector(".cv-error");
+    this.errorText = this.el.querySelector(".cv-error-text");
+    this.timerEl = this.el.querySelector(".cv-timer");
+    this.canvas = this.el.querySelector(".cv-canvas");
+    this.muteBtn = this.el.querySelector(".cv-btn--mute");
+    this.stopBtn = this.el.querySelector(".cv-btn--end");
+    this.visualizerWrap = this.el.querySelector(".cv-visualizer-wrap");
+    this.startBtn.addEventListener("click", () => this.start());
+    this.stopBtn.addEventListener("click", () => this.stop());
+    this.muteBtn.addEventListener("click", () => this.toggleMute());
+  }
+  esc(s) {
+    const d = document.createElement("div");
+    d.textContent = s;
+    return d.innerHTML;
+  }
+  /** Start the conversation (called when user clicks "Start Conversation" or externally) */
+  async start() {
+    if (this.isRunning) return;
+    this.isRunning = true;
+    this.startBtn.disabled = true;
+    this.errorEl.classList.remove("is-visible");
+    this.playConnectingSound();
+    try {
+      const ConvoAgent = this.cfg.ConvoAgent;
+      const SphereVisualizer = this.cfg.SphereVisualizer;
+      const visualizer = new SphereVisualizer(this.canvas);
+      visualizer.resize(280, 280);
+      this.visualizer = visualizer;
+      if (this.cfg.accentColor && typeof visualizer.setAccentColor === "function") {
+        const hex = this.cfg.accentColor;
+        visualizer.setAccentColor(
+          parseInt(hex.slice(1, 3), 16) / 255,
+          parseInt(hex.slice(3, 5), 16) / 255,
+          parseInt(hex.slice(5, 7), 16) / 255
+        );
+      }
+      const agentHandle = new ConvoAgent({
+        apiKey: this.cfg.apiKey,
+        prompt: this.cfg.prompt,
+        voice: this.cfg.voice || "M1",
+        language: this.cfg.language || "en",
+        onStatusChange: (status) => {
+          this.el.classList.remove("cv-is-speaking", "cv-is-thinking");
+          if (status === "speaking") this.el.classList.add("cv-is-speaking");
+          else if (status === "thinking") this.el.classList.add("cv-is-thinking");
+        },
+        onTranscription: (text) => {
+          this.onTranscription?.(text);
+        },
+        onResponse: (text) => {
+          this.onResponse?.(text);
+        },
+        onError: (err) => {
+          if (!this.isRunning) return;
+          this.onError?.(err);
+          this.stop();
+          this.showError("Connection issue. Try again in a moment.");
+        }
+      });
+      this.agent = agentHandle;
+      visualizer.setAudioClient(agentHandle);
+      this.curtain.classList.add("is-up");
+      try {
+        agentHandle.unlockAudioForMobile?.();
+      } catch (_) {
+      }
+      const ok = await agentHandle.connect();
+      if (ok) {
+        this.fadeOutConnectingSound();
+        const wrap = this.visualizerWrap;
+        if (wrap) {
+          const dpr = Math.min(window.devicePixelRatio || 1, 2);
+          const w = Math.floor(wrap.clientWidth * dpr);
+          const h = Math.floor(wrap.clientHeight * dpr);
+          visualizer.resize(w, h);
+        }
+        visualizer.start();
+        this.startTimer();
+        this.onStart?.();
+        if (window.lucide) window.lucide.createIcons();
+      } else {
+        this.fadeOutConnectingSound();
+        this.playErrorTone();
+        this.curtain.classList.remove("is-up");
+        this.showError("Could not connect. Please try again.");
+        this.isRunning = false;
+      }
+    } catch (err) {
+      this.fadeOutConnectingSound();
+      this.playErrorTone();
+      console.error("ConversationalPanel start error:", err);
+      this.stop();
+      this.showError("Something went wrong. Please try again.");
+    } finally {
+      this.startBtn.disabled = false;
+    }
+  }
+  /** Stop / disconnect the conversation */
+  stop() {
+    if (!this.isRunning && !this.agent && !this.visualizer) return;
+    this.isRunning = false;
+    this.fadeOutConnectingSound();
+    this.errorEl.classList.remove("is-visible");
+    if (this.agent) {
+      try {
+        this.agent.disconnect();
+      } catch (_) {
+      }
+      this.agent = null;
+    }
+    if (this.timerTicker) {
+      clearInterval(this.timerTicker);
+      this.timerTicker = null;
+    }
+    if (this.visualizer) {
+      this.visualizer.stop();
+      this.visualizer = null;
+    }
+    this.curtain.classList.remove("is-up");
+    this.el.classList.remove("cv-is-speaking", "cv-is-thinking");
+    this.muteBtn.classList.remove("is-muted");
+    const span = this.muteBtn.querySelector("span");
+    if (span) span.textContent = "Mute";
+    this.onStop?.();
+    this.startBtn.disabled = false;
+  }
+  /** Update accent color dynamically */
+  setColor(color) {
+    this.cfg.accentColor = color;
+    this.container.style.setProperty("--cv-accent", color);
+    if (this.visualizer && typeof this.visualizer.setAccentColor === "function") {
+      const r = parseInt(color.slice(1, 3), 16) / 255;
+      const g = parseInt(color.slice(3, 5), 16) / 255;
+      const b = parseInt(color.slice(5, 7), 16) / 255;
+      this.visualizer.setAccentColor(r, g, b);
+    }
+  }
+  /** Update title text */
+  setTitle(title) {
+    this.cfg.title = title;
+    this.curtainTitle.textContent = title;
+    const h2 = this.el.querySelector(".cv-title");
+    if (h2) h2.innerHTML = `${this.esc(title)} <span class="cv-timer">${this.timerEl?.textContent || "00:00"}</span>`;
+  }
+  /** Update description text */
+  setDescription(desc) {
+    this.cfg.description = desc;
+    this.curtainDesc.textContent = desc;
+  }
+  /** Update prompt (only takes effect on next start()) */
+  setPrompt(prompt) {
+    this.cfg.prompt = prompt;
+  }
+  /** Show an error message */
+  showError(text) {
+    this.errorText.textContent = text;
+    this.errorEl.classList.add("is-visible");
+    setTimeout(() => {
+      this.errorEl.classList.remove("is-visible");
+    }, 5e3);
+  }
+  /** Destroy the component, removing all DOM and stopping any active session */
+  destroy() {
+    this.stop();
+    this.el.remove();
+  }
+  // ─── internal helpers ────────────────────────────────────
+  startTimer() {
+    let elapsed = 0;
+    this.timerEl.textContent = "00:00";
+    this.timerTicker = window.setInterval(() => {
+      elapsed++;
+      const m = Math.floor(elapsed / 60).toString().padStart(2, "0");
+      const s = (elapsed % 60).toString().padStart(2, "0");
+      this.timerEl.textContent = `${m}:${s}`;
+    }, 1e3);
+  }
+  toggleMute() {
+    if (!this.agent) return;
+    try {
+      const muted = this.agent.toggleMute();
+      this.muteBtn.classList.toggle("is-muted", muted);
+      const span = this.muteBtn.querySelector("span");
+      if (span) span.textContent = muted ? "Unmute" : "Mute";
+      if (muted) {
+        this.agent.pauseAudio?.();
+        this.visualizer?.setDeactivated?.(true);
+      } else {
+        this.agent.resumeAudio?.();
+        this.visualizer?.setDeactivated?.(false);
+      }
+    } catch (_) {
+    }
+  }
+  playConnectingSound() {
+    this.fadeOutConnectingSound();
+    const src = this.cfg.connectingSoundSrc || "/connecting.mp3";
+    this.connectingSound = new Audio(src);
+    this.connectingSound.volume = 0.6;
+    this.connectingSound.play().catch(() => {
+    });
+  }
+  fadeOutConnectingSound() {
+    if (this.connectingFadeTimer) {
+      clearInterval(this.connectingFadeTimer);
+      this.connectingFadeTimer = null;
+    }
+    if (!this.connectingSound) return;
+    const startVol = this.connectingSound.volume;
+    const steps = 15;
+    let step = 0;
+    this.connectingFadeTimer = window.setInterval(() => {
+      step++;
+      const progress = step / steps;
+      if (this.connectingSound) this.connectingSound.volume = startVol * Math.max(0, 1 - progress);
+      if (step >= steps) {
+        if (this.connectingFadeTimer) {
+          clearInterval(this.connectingFadeTimer);
+          this.connectingFadeTimer = null;
+        }
+        if (this.connectingSound) {
+          this.connectingSound.pause();
+          this.connectingSound.currentTime = 0;
+          this.connectingSound = null;
+        }
+      }
+    }, 100);
+  }
+  playErrorTone() {
+    try {
+      const ctx = new (window.AudioContext || window.webkitAudioContext)();
+      const now = ctx.currentTime;
+      [0, 0.3].forEach((offset, i) => {
+        const osc = ctx.createOscillator();
+        const gain = ctx.createGain();
+        osc.connect(gain);
+        gain.connect(ctx.destination);
+        osc.type = "sine";
+        osc.frequency.setValueAtTime(600 - i * 200, now + offset);
+        gain.gain.setValueAtTime(0.25, now + offset);
+        gain.gain.exponentialRampToValueAtTime(1e-3, now + offset + 0.35);
+        osc.start(now + offset);
+        osc.stop(now + offset + 0.4);
+      });
+    } catch (_) {
+    }
+  }
+};
 export {
   AUDIO_CONFIG,
   BrowserAudioManager,
+  ConversationalPanel,
   DEFAULT_URLS,
   Language,
+  LokutorError,
   StreamResampler,
   TTSClient,
   VoiceAgentClient,
@@ -899,6 +1795,7 @@ export {
   bytesToPcm16,
   calculateRMS,
   float32ToPcm16,
+  isRetryable,
   normalizeAudio,
   pcm16ToBytes,
   pcm16ToFloat32,