@runtypelabs/persona 1.47.0 → 1.48.0

package/dist/widget.css

@@ -1060,6 +1060,30 @@
   animation: tvw-voice-recording-pulse 1.5s ease-in-out infinite;
 }
 
+/* Voice processing animation (spinner) */
+@keyframes tvw-voice-processing-spin {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+
+.tvw-voice-processing svg {
+  animation: tvw-voice-processing-spin 1.2s linear infinite;
+}
+
+/* Voice speaking animation (gentle pulse — slower/subtler than recording) */
+@keyframes tvw-voice-speaking-pulse {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50% { opacity: 0.85; transform: scale(1.03); }
+}
+
+.tvw-voice-speaking {
+  animation: tvw-voice-speaking-pulse 2s ease-in-out infinite;
+}
+
+.tvw-voice-speaking svg {
+  animation: tvw-voice-speaking-pulse 2s ease-in-out infinite;
+}
+
 /* Markdown content overflow handling */
 .vanilla-message-bubble pre {
   overflow-x: auto;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/session.ts

@@ -19,14 +19,12 @@ import {
 import { IMAGE_ONLY_MESSAGE_FALLBACK_TEXT } from "./utils/content";
 import type {
   VoiceProvider,
-  VoiceResult,
   VoiceStatus,
   VoiceConfig,
   TextToSpeechConfig
 } from "./types";
 import {
   createVoiceProvider,
-  createBestAvailableVoiceProvider,
   isVoiceSupported
 } from "./voice";
 
@@ -136,6 +134,38 @@ export class AgentWidgetSession {
     return this.voiceStatus;
   }
 
+  /**
+   * Get the voice interruption mode from the provider (none/cancel/barge-in)
+   */
+  public getVoiceInterruptionMode(): "none" | "cancel" | "barge-in" {
+    if (this.voiceProvider?.getInterruptionMode) {
+      return this.voiceProvider.getInterruptionMode();
+    }
+    return "none";
+  }
+
+  /**
+   * Stop voice playback / cancel in-flight request without starting recording.
+   * Returns to idle state.
+   */
+  public stopVoicePlayback(): void {
+    if (this.voiceProvider?.stopPlayback) {
+      this.voiceProvider.stopPlayback();
+    }
+  }
+
+  /** Returns true if the barge-in mic stream is alive (hot mic between turns) */
+  public isBargeInActive(): boolean {
+    return this.voiceProvider?.isBargeInActive?.() ?? false;
+  }
+
+  /** Tear down the barge-in mic pipeline — "hang up" the always-on mic */
+  public async deactivateBargeIn(): Promise<void> {
+    if (this.voiceProvider?.deactivateBargeIn) {
+      await this.voiceProvider.deactivateBargeIn();
+    }
+  }
+
   // Pending placeholder IDs for Runtype two-phase voice flow
   private pendingVoiceUserMessageId: string | null = null;
   private pendingVoiceAssistantMessageId: string | null = null;
@@ -227,9 +257,12 @@ export class AgentWidgetSession {
             this.injectAssistantMessage({ content: result.text.trim() });
           }
 
-          // If Runtype provider returned audio (server-side TTS), mark the
-          // assistant message as already spoken so browser TTS doesn't double-speak
-          if (result.audio?.base64) {
+          // Mark assistant message as already spoken so browser TTS doesn't
+          // double-speak. This covers both paths:
+          //   - Batch: audio.base64 is present in the voice_response
+          //   - Streaming: audio arrives as binary PCM chunks (no base64 here)
+          // In either case, the Runtype provider handles TTS — browser TTS must skip.
+          {
             const spokenId = this.pendingVoiceAssistantMessageId
               ?? [...this.messages].reverse().find(m => m.role === 'assistant')?.id;
             if (spokenId) this.ttsSpokenMessageIds.add(spokenId);

package/src/styles/widget.css

@@ -1060,6 +1060,30 @@
   animation: tvw-voice-recording-pulse 1.5s ease-in-out infinite;
 }
 
+/* Voice processing animation (spinner) */
+@keyframes tvw-voice-processing-spin {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+
+.tvw-voice-processing svg {
+  animation: tvw-voice-processing-spin 1.2s linear infinite;
+}
+
+/* Voice speaking animation (gentle pulse — slower/subtler than recording) */
+@keyframes tvw-voice-speaking-pulse {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50% { opacity: 0.85; transform: scale(1.03); }
+}
+
+.tvw-voice-speaking {
+  animation: tvw-voice-speaking-pulse 2s ease-in-out infinite;
+}
+
+.tvw-voice-speaking svg {
+  animation: tvw-voice-speaking-pulse 2s ease-in-out infinite;
+}
+
 /* Markdown content overflow handling */
 .vanilla-message-bubble pre {
   overflow-x: auto;

package/src/types.ts

@@ -696,6 +696,26 @@ export type AgentWidgetVoiceRecognitionConfig = {
   recordingBackgroundColor?: string;
   recordingBorderColor?: string;
   showRecordingIndicator?: boolean;
+
+  // Processing state (after recording stops, waiting for agent response)
+  /** Icon name shown while processing voice input. Default: "loader" */
+  processingIconName?: string;
+  /** Icon color during processing. Inherits idle iconColor if not set */
+  processingIconColor?: string;
+  /** Button background color during processing. Inherits idle backgroundColor if not set */
+  processingBackgroundColor?: string;
+  /** Button border color during processing. Inherits idle borderColor if not set */
+  processingBorderColor?: string;
+
+  // Speaking state (agent TTS audio is playing)
+  /** Icon name shown while agent is speaking. Default: "volume-2" (or "square" in cancel mode) */
+  speakingIconName?: string;
+  /** Icon color while speaking. Inherits idle iconColor if not set */
+  speakingIconColor?: string;
+  /** Button background color while speaking. Inherits idle backgroundColor if not set */
+  speakingBackgroundColor?: string;
+  /** Button border color while speaking. Inherits idle borderColor if not set */
+  speakingBorderColor?: string;
   autoResume?: boolean | "assistant";
   
   // Voice provider configuration
@@ -794,11 +814,12 @@ export type VoiceResult = {
 /**
  * Voice provider status states
  */
-export type VoiceStatus = 
+export type VoiceStatus =
   | 'disconnected'
   | 'connected'
   | 'listening'
   | 'processing'
+  | 'speaking'
   | 'error'
   | 'idle';
 
@@ -843,6 +864,18 @@ export interface VoiceProvider {
 
   /** Register a callback fired when recording stops and audio is about to be sent */
   onProcessingStart?(callback: () => void): void;
+
+  /** Returns the current interruption mode (only meaningful for Runtype provider) */
+  getInterruptionMode?(): "none" | "cancel" | "barge-in";
+
+  /** Returns true if the barge-in mic stream is alive (hot mic between turns) */
+  isBargeInActive?(): boolean;
+
+  /** Tear down the barge-in mic pipeline — "hang up" the always-on mic */
+  deactivateBargeIn?(): Promise<void>;
+
+  /** Stop playback / cancel in-flight request without starting recording */
+  stopPlayback?(): void;
 }
 
 /**

package/src/ui.ts

@@ -2053,12 +2053,34 @@ export const createAgentExperience = (
       }
     },
     onVoiceStatusChanged(status: VoiceStatus) {
-      // When Runtype provider auto-stops (e.g. silence detection), update mic button
-      if (config.voiceRecognition?.provider?.type === 'runtype' && status !== 'listening') {
-        voiceState.active = false;
-        removeRuntypeMicRecordingStyles();
-        emitVoiceState("system");
-        persistVoiceMetadata();
+      if (config.voiceRecognition?.provider?.type !== 'runtype') return;
+
+      switch (status) {
+        case 'listening':
+          // Recording styles are applied by toggleVoice() / startVoiceRecognition() flows
+          break;
+        case 'processing':
+          removeRuntypeMicStateStyles();
+          applyRuntypeMicProcessingStyles();
+          break;
+        case 'speaking':
+          removeRuntypeMicStateStyles();
+          applyRuntypeMicSpeakingStyles();
+          break;
+        default:
+          // idle, connected, disconnected, error
+          if (status === 'idle' && session.isBargeInActive()) {
+            // Barge-in mic is still hot between turns — show it as active
+            removeRuntypeMicStateStyles();
+            applyRuntypeMicRecordingStyles();
+            micButton?.setAttribute("aria-label", "End voice session");
+          } else {
+            voiceState.active = false;
+            removeRuntypeMicStateStyles();
+            emitVoiceState("system");
+            persistVoiceMetadata();
+          }
+          break;
       }
     }
   });
@@ -2176,6 +2198,8 @@ export const createAgentExperience = (
     backgroundColor: string;
     color: string;
     borderColor: string;
+    iconName: string;
+    iconSize: number;
   } | null = null;
 
   const getSpeechRecognitionClass = (): any => {
@@ -2273,15 +2297,17 @@ export const createAgentExperience = (
       emitVoiceState(source);
       persistVoiceMetadata();
       if (micButton) {
-        // Store original styles
+        // Store original styles (including icon info for restoration)
+        const voiceConfig = config.voiceRecognition ?? {};
         originalMicStyles = {
           backgroundColor: micButton.style.backgroundColor,
           color: micButton.style.color,
-          borderColor: micButton.style.borderColor
+          borderColor: micButton.style.borderColor,
+          iconName: voiceConfig.iconName ?? "mic",
+          iconSize: parseFloat(voiceConfig.iconSize ?? config.sendButton?.size ?? "40") || 24,
         };
-        
+
         // Apply recording state styles from config
-        const voiceConfig = config.voiceRecognition ?? {};
         const recordingBackgroundColor = voiceConfig.recordingBackgroundColor ?? "#ef4444";
         const recordingIconColor = voiceConfig.recordingIconColor;
         const recordingBorderColor = voiceConfig.recordingBorderColor;
@@ -2334,24 +2360,7 @@ export const createAgentExperience = (
     persistVoiceMetadata();
 
     if (micButton) {
-      micButton.classList.remove("tvw-voice-recording");
-      
-      // Restore original styles
-      if (originalMicStyles) {
-        micButton.style.backgroundColor = originalMicStyles.backgroundColor;
-        micButton.style.color = originalMicStyles.color;
-        micButton.style.borderColor = originalMicStyles.borderColor;
-        
-        // Restore SVG stroke color if present
-        const svg = micButton.querySelector("svg");
-        if (svg) {
-          svg.setAttribute("stroke", originalMicStyles.color || "currentColor");
-        }
-        
-        originalMicStyles = null;
-      }
-      
-      micButton.setAttribute("aria-label", "Start voice recognition");
+      removeRuntypeMicStateStyles();
     }
   };
 
@@ -2450,18 +2459,46 @@ export const createAgentExperience = (
     return { micButton, micButtonWrapper };
   };
 
-  // Helpers to apply/remove Runtype mic recording styles (mirrors start/stopVoiceRecognition)
-  const applyRuntypeMicRecordingStyles = () => {
-    if (!micButton) return;
+  // --- Helpers to store/restore original mic button state ---
+
+  const storeOriginalMicStyles = () => {
+    if (!micButton || originalMicStyles) return; // Already stored
+    const voiceConfig = config.voiceRecognition ?? {};
     originalMicStyles = {
       backgroundColor: micButton.style.backgroundColor,
       color: micButton.style.color,
-      borderColor: micButton.style.borderColor
+      borderColor: micButton.style.borderColor,
+      iconName: voiceConfig.iconName ?? "mic",
+      iconSize: parseFloat(voiceConfig.iconSize ?? config.sendButton?.size ?? "40") || 24,
     };
+  };
+
+  /** Swap the mic button's SVG icon */
+  const swapMicIcon = (iconName: string, color: string) => {
+    if (!micButton) return;
+    const existingSvg = micButton.querySelector("svg");
+    if (existingSvg) existingSvg.remove();
+    const size = originalMicStyles?.iconSize ?? (parseFloat(config.voiceRecognition?.iconSize ?? config.sendButton?.size ?? "40") || 24);
+    const newSvg = renderLucideIcon(iconName, size, color, 1.5);
+    if (newSvg) micButton.appendChild(newSvg);
+  };
+
+  /** Remove all voice state CSS classes */
+  const removeAllVoiceStateClasses = () => {
+    if (!micButton) return;
+    micButton.classList.remove("tvw-voice-recording", "tvw-voice-processing", "tvw-voice-speaking");
+  };
+
+  // --- Per-state style application ---
+
+  const applyRuntypeMicRecordingStyles = () => {
+    if (!micButton) return;
+    storeOriginalMicStyles();
     const voiceConfig = config.voiceRecognition ?? {};
     const recordingBackgroundColor = voiceConfig.recordingBackgroundColor ?? "#ef4444";
     const recordingIconColor = voiceConfig.recordingIconColor;
     const recordingBorderColor = voiceConfig.recordingBorderColor;
+    removeAllVoiceStateClasses();
     micButton.classList.add("tvw-voice-recording");
     micButton.style.backgroundColor = recordingBackgroundColor;
     if (recordingIconColor) {
@@ -2472,17 +2509,86 @@ export const createAgentExperience = (
     if (recordingBorderColor) micButton.style.borderColor = recordingBorderColor;
     micButton.setAttribute("aria-label", "Stop voice recognition");
   };
-  const removeRuntypeMicRecordingStyles = () => {
+
+  const applyRuntypeMicProcessingStyles = () => {
     if (!micButton) return;
-    micButton.classList.remove("tvw-voice-recording");
+    storeOriginalMicStyles();
+    const voiceConfig = config.voiceRecognition ?? {};
+    const interruptionMode = session.getVoiceInterruptionMode();
+    const iconName = voiceConfig.processingIconName ?? "loader";
+    const iconColor = voiceConfig.processingIconColor ?? originalMicStyles?.color ?? "";
+    const bgColor = voiceConfig.processingBackgroundColor ?? originalMicStyles?.backgroundColor ?? "";
+    const borderColor = voiceConfig.processingBorderColor ?? originalMicStyles?.borderColor ?? "";
+
+    removeAllVoiceStateClasses();
+    micButton.classList.add("tvw-voice-processing");
+    micButton.style.backgroundColor = bgColor;
+    micButton.style.borderColor = borderColor;
+    const resolvedColor = iconColor || "currentColor";
+    micButton.style.color = resolvedColor;
+    swapMicIcon(iconName, resolvedColor);
+    micButton.setAttribute("aria-label", "Processing voice input");
+    // In "none" mode the button is not actionable during processing
+    if (interruptionMode === "none") {
+      micButton.style.cursor = "default";
+    }
+  };
+
+  const applyRuntypeMicSpeakingStyles = () => {
+    if (!micButton) return;
+    storeOriginalMicStyles();
+    const voiceConfig = config.voiceRecognition ?? {};
+    const interruptionMode = session.getVoiceInterruptionMode();
+    // Default icon depends on interruption mode:
+    // "square" for cancel, "mic" for barge-in (hot mic), "volume-2" otherwise
+    const defaultSpeakingIcon = interruptionMode === "cancel" ? "square"
+      : interruptionMode === "barge-in" ? "mic"
+      : "volume-2";
+    const iconName = voiceConfig.speakingIconName ?? defaultSpeakingIcon;
+    const iconColor = voiceConfig.speakingIconColor
+      ?? (interruptionMode === "barge-in" ? (voiceConfig.recordingIconColor ?? originalMicStyles?.color ?? "") : (originalMicStyles?.color ?? ""));
+    const bgColor = voiceConfig.speakingBackgroundColor
+      ?? (interruptionMode === "barge-in" ? (voiceConfig.recordingBackgroundColor ?? "#ef4444") : (originalMicStyles?.backgroundColor ?? ""));
+    const borderColor = voiceConfig.speakingBorderColor
+      ?? (interruptionMode === "barge-in" ? (voiceConfig.recordingBorderColor ?? "") : (originalMicStyles?.borderColor ?? ""));
+
+    removeAllVoiceStateClasses();
+    micButton.classList.add("tvw-voice-speaking");
+    micButton.style.backgroundColor = bgColor;
+    micButton.style.borderColor = borderColor;
+    const resolvedColor = iconColor || "currentColor";
+    micButton.style.color = resolvedColor;
+    swapMicIcon(iconName, resolvedColor);
+
+    // aria-label varies by interruption mode
+    const ariaLabel = interruptionMode === "cancel"
+      ? "Stop playback and re-record"
+      : interruptionMode === "barge-in"
+      ? "Speak to interrupt"
+      : "Agent is speaking";
+    micButton.setAttribute("aria-label", ariaLabel);
+    // In "none" mode the button is not actionable during speaking
+    if (interruptionMode === "none") {
+      micButton.style.cursor = "default";
+    }
+    // In "barge-in" mode, add recording class to show mic is hot
+    if (interruptionMode === "barge-in") {
+      micButton.classList.add("tvw-voice-recording");
+    }
+  };
+
+  /** Restore mic button to idle state (icon, colors, aria-label, cursor) */
+  const removeRuntypeMicStateStyles = () => {
+    if (!micButton) return;
+    removeAllVoiceStateClasses();
     if (originalMicStyles) {
       micButton.style.backgroundColor = originalMicStyles.backgroundColor ?? "";
       micButton.style.color = originalMicStyles.color ?? "";
       micButton.style.borderColor = originalMicStyles.borderColor ?? "";
-      const svg = micButton.querySelector("svg");
-      if (svg) svg.setAttribute("stroke", originalMicStyles.color || "currentColor");
+      swapMicIcon(originalMicStyles.iconName, originalMicStyles.color || "currentColor");
       originalMicStyles = null;
     }
+    micButton.style.cursor = "";
     micButton.setAttribute("aria-label", "Start voice recognition");
   };
 
@@ -2490,6 +2596,36 @@ export const createAgentExperience = (
   const handleMicButtonClick = () => {
     // Runtype provider: use session.toggleVoice() (WebSocket-based STT)
     if (config.voiceRecognition?.provider?.type === 'runtype') {
+      const voiceStatus = session.getVoiceStatus();
+      const interruptionMode = session.getVoiceInterruptionMode();
+
+      // In "none" mode, ignore clicks while processing or speaking
+      if (interruptionMode === "none" &&
+          (voiceStatus === "processing" || voiceStatus === "speaking")) {
+        return;
+      }
+
+      // In "cancel" mode during processing/speaking: stop playback only
+      if (interruptionMode === "cancel" &&
+          (voiceStatus === "processing" || voiceStatus === "speaking")) {
+        session.stopVoicePlayback();
+        return;
+      }
+
+      // In barge-in mode, clicking mic = "hang up" (any state: speaking, idle, etc.)
+      // Stops playback if active, tears down the always-on mic.
+      if (session.isBargeInActive()) {
+        session.stopVoicePlayback();
+        session.deactivateBargeIn().then(() => {
+          voiceState.active = false;
+          voiceState.manuallyDeactivated = true;
+          persistVoiceMetadata();
+          emitVoiceState("user");
+          removeRuntypeMicStateStyles();
+        });
+        return;
+      }
+
       session.toggleVoice().then(() => {
         voiceState.active = session.isVoiceActive();
         voiceState.manuallyDeactivated = !session.isVoiceActive();
@@ -2498,7 +2634,7 @@ export const createAgentExperience = (
         if (session.isVoiceActive()) {
           applyRuntypeMicRecordingStyles();
         } else {
-          removeRuntypeMicRecordingStyles();
+          removeRuntypeMicStateStyles();
         }
       });
       return;
@@ -2530,7 +2666,7 @@ export const createAgentExperience = (
     destroyCallbacks.push(() => {
       if (config.voiceRecognition?.provider?.type === 'runtype') {
         if (session.isVoiceActive()) session.toggleVoice();
-        removeRuntypeMicRecordingStyles();
+        removeRuntypeMicStateStyles();
       } else {
         stopVoiceRecognition("system");
       }
@@ -4102,7 +4238,7 @@ export const createAgentExperience = (
           voiceState.manuallyDeactivated = true;
           persistVoiceMetadata();
           emitVoiceState("user");
-          removeRuntypeMicRecordingStyles();
+          removeRuntypeMicStateStyles();
         });
         return true;
       }

package/src/voice/audio-playback-manager.ts

@@ -0,0 +1,187 @@
+/**
+ * AudioPlaybackManager
+ *
+ * Manages streaming playback of PCM audio chunks via the Web Audio API.
+ * Receives raw PCM data (24 kHz, 16-bit signed little-endian, mono),
+ * converts to Float32 AudioBuffers, and schedules gap-free sequential
+ * playback using AudioBufferSourceNode.
+ *
+ * Works on all browsers including iOS Safari (no MediaSource dependency).
+ */
+export class AudioPlaybackManager {
+  private ctx: AudioContext | null = null;
+  private nextStartTime = 0;
+  private activeSources: AudioBufferSourceNode[] = [];
+  private finishedCallbacks: (() => void)[] = [];
+  private playing = false;
+  private streamEnded = false;
+  private pendingCount = 0;
+
+  // PCM format constants
+  private readonly sampleRate: number;
+
+  // Remainder byte from a previous chunk when the chunk had an odd byte count.
+  // Network chunks don't respect 2-byte sample boundaries, so we carry over
+  // the orphaned byte and prepend it to the next chunk.
+  private remainder: Uint8Array | null = null;
+
+  constructor(sampleRate = 24000) {
+    this.sampleRate = sampleRate;
+  }
+
+  /**
+   * Ensure AudioContext is created and running.
+   * Must be called after a user gesture on iOS Safari.
+   */
+  private ensureContext(): AudioContext {
+    if (!this.ctx) {
+      const w = typeof window !== "undefined" ? (window as any) : undefined;
+      if (!w) throw new Error("AudioPlaybackManager requires a browser environment");
+      const AudioCtx = w.AudioContext || w.webkitAudioContext;
+      this.ctx = new AudioCtx({ sampleRate: this.sampleRate }) as AudioContext;
+    }
+    const ctx = this.ctx!;
+    // Resume if suspended (autoplay policy)
+    if (ctx.state === "suspended") {
+      ctx.resume();
+    }
+    return ctx;
+  }
+
+  /**
+   * Enqueue a PCM chunk for playback.
+   * @param pcmData Raw PCM bytes (16-bit signed LE mono)
+   */
+  enqueue(pcmData: Uint8Array): void {
+    if (pcmData.length === 0) return;
+
+    // Prepend any remainder byte from the previous chunk
+    let data = pcmData;
+    if (this.remainder) {
+      const merged = new Uint8Array(this.remainder.length + pcmData.length);
+      merged.set(this.remainder);
+      merged.set(pcmData, this.remainder.length);
+      data = merged;
+      this.remainder = null;
+    }
+
+    // If odd byte count, save the trailing byte for next chunk
+    if (data.length % 2 !== 0) {
+      this.remainder = new Uint8Array([data[data.length - 1]]);
+      data = data.subarray(0, data.length - 1);
+    }
+
+    if (data.length === 0) return;
+
+    const ctx = this.ensureContext();
+    const float32 = this.pcmToFloat32(data);
+
+    const buffer = ctx.createBuffer(1, float32.length, this.sampleRate);
+    buffer.getChannelData(0).set(float32);
+
+    const source = ctx.createBufferSource();
+    source.buffer = buffer;
+    source.connect(ctx.destination);
+
+    // Schedule gap-free playback
+    const now = ctx.currentTime;
+    if (this.nextStartTime < now) {
+      this.nextStartTime = now;
+    }
+    source.start(this.nextStartTime);
+    this.nextStartTime += buffer.duration;
+
+    this.activeSources.push(source);
+    this.pendingCount++;
+    this.playing = true;
+
+    source.onended = () => {
+      const idx = this.activeSources.indexOf(source);
+      if (idx !== -1) this.activeSources.splice(idx, 1);
+      this.pendingCount--;
+      this.checkFinished();
+    };
+  }
+
+  /**
+   * Signal that no more chunks will arrive.
+   * The onFinished callback fires after all queued audio has played.
+   */
+  markStreamEnd(): void {
+    this.streamEnded = true;
+    this.checkFinished();
+  }
+
+  /**
+   * Immediately stop all playback and discard queued audio.
+   */
+  flush(): void {
+    for (const source of this.activeSources) {
+      try {
+        source.stop();
+        source.disconnect();
+      } catch {
+        // Ignore errors from already-stopped sources
+      }
+    }
+    this.activeSources = [];
+    this.pendingCount = 0;
+    this.nextStartTime = 0;
+    this.playing = false;
+    this.streamEnded = false;
+    this.finishedCallbacks = [];
+    this.remainder = null;
+  }
+
+  /**
+   * Whether audio is currently playing or queued.
+   */
+  isPlaying(): boolean {
+    return this.playing;
+  }
+
+  /**
+   * Register a callback for when all queued audio finishes playing.
+   */
+  onFinished(callback: () => void): void {
+    this.finishedCallbacks.push(callback);
+  }
+
+  /**
+   * Clean up AudioContext resources.
+   */
+  async destroy(): Promise<void> {
+    this.flush();
+    if (this.ctx) {
+      await this.ctx.close();
+      this.ctx = null;
+    }
+  }
+
+  private checkFinished(): void {
+    if (this.streamEnded && this.pendingCount <= 0 && this.playing) {
+      this.playing = false;
+      this.streamEnded = false;
+      const cbs = this.finishedCallbacks.slice();
+      this.finishedCallbacks = [];
+      for (const cb of cbs) cb();
+    }
+  }
+
+  /**
+   * Convert 16-bit signed LE PCM to Float32 samples in [-1, 1].
+   */
+  private pcmToFloat32(pcmData: Uint8Array): Float32Array {
+    // 2 bytes per sample (16-bit)
+    const numSamples = Math.floor(pcmData.length / 2);
+    const float32 = new Float32Array(numSamples);
+    const view = new DataView(pcmData.buffer, pcmData.byteOffset, pcmData.byteLength);
+
+    for (let i = 0; i < numSamples; i++) {
+      const int16 = view.getInt16(i * 2, true); // little-endian
+      float32[i] = int16 / 32768;
+    }
+
+    return float32;
+  }
+}