@tryhamster/gerbil 1.0.0-rc.0 → 1.0.0-rc.1

package/dist/browser/index.mjs

@@ -1,4 +1,4 @@
-import { a as resolveModel, t as BUILTIN_MODELS } from "../models-DKULvhOr.mjs";
+import { o as resolveModel, t as BUILTIN_MODELS } from "../models-BAtL8qsA.mjs";
 
 //#region src/browser/index.ts
 /**
@@ -61,40 +61,84 @@ async function createGerbilWorker(options = {}) {
       import {
         AutoTokenizer,
         AutoModelForCausalLM,
+        AutoProcessor,
+        AutoModelForImageTextToText,
+        RawImage,
         TextStreamer,
         InterruptableStoppingCriteria,
-      } from "https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.8.0";
+        env,
+      } from "https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.8.1";
+
+      // Enable IndexedDB caching for browser (prevents re-downloading models)
+      env.useBrowserCache = true;
+      env.allowLocalModels = false;
 
       class ModelPipeline {
         static tokenizer = null;
         static model = null;
+        static processor = null;
+        static visionModel = null;
         static modelId = "";
+        static isVision = false;
 
         static async getInstance(modelId, options = {}, progressCallback) {
           if (this.modelId !== modelId) {
             this.tokenizer = null;
             this.model = null;
+            this.processor = null;
+            this.visionModel = null;
           }
           this.modelId = modelId;
+          
+          // Detect vision models
+          this.isVision = options.vision || 
+            modelId.toLowerCase().includes("ministral") ||
+            modelId.toLowerCase().includes("vision") ||
+            modelId.toLowerCase().includes("vlm");
 
           const dtype = options.dtype || "q4f16";
           const device = options.device || "webgpu";
 
-          if (!this.tokenizer) {
-            this.tokenizer = await AutoTokenizer.from_pretrained(modelId, {
-              progress_callback: progressCallback,
-            });
-          }
-
-          if (!this.model) {
-            this.model = await AutoModelForCausalLM.from_pretrained(modelId, {
-              dtype,
-              device,
-              progress_callback: progressCallback,
-            });
+          if (this.isVision) {
+            // Load vision model components
+            // Note: Don't specify dtype for vision models - let transformers.js pick defaults
+            if (!this.processor) {
+              this.processor = await AutoProcessor.from_pretrained(modelId, {
+                progress_callback: progressCallback,
+              });
+            }
+            if (!this.visionModel) {
+              this.visionModel = await AutoModelForImageTextToText.from_pretrained(modelId, {
+                device,
+                progress_callback: progressCallback,
+              });
+            }
+            return { 
+              processor: this.processor, 
+              model: this.visionModel, 
+              tokenizer: this.processor.tokenizer,
+              isVision: true 
+            };
+          } else {
+            // Load text-only model components
+            if (!this.tokenizer) {
+              this.tokenizer = await AutoTokenizer.from_pretrained(modelId, {
+                progress_callback: progressCallback,
+              });
+            }
+            if (!this.model) {
+              this.model = await AutoModelForCausalLM.from_pretrained(modelId, {
+                dtype,
+                device,
+                progress_callback: progressCallback,
+              });
+            }
+            return { 
+              tokenizer: this.tokenizer, 
+              model: this.model, 
+              isVision: false 
+            };
           }
-
-          return { tokenizer: this.tokenizer, model: this.model };
         }
       }
 
@@ -105,22 +149,19 @@ async function createGerbilWorker(options = {}) {
         const { modelId, options = {} } = data;
         self.postMessage({ status: "loading", message: "Loading model..." });
 
-        // Track download state - if we see progress < 100, we're downloading
         const downloadState = {
-          downloading: new Set(),  // Files currently downloading
-          completed: new Set(),    // Files completed
-          isDownloading: false,    // True if any file needed download
+          downloading: new Set(),
+          completed: new Set(),
+          isDownloading: false,
         };
 
         try {
-          const { tokenizer, model } = await ModelPipeline.getInstance(
+          const result = await ModelPipeline.getInstance(
             modelId,
             options,
             (progress) => {
               if (progress.status === "progress" && progress.file) {
                 const pct = Math.round(progress.progress || 0);
-                
-                // If we see progress < 100, this file is being downloaded (not from cache)
                 if (pct < 100) {
                   downloadState.downloading.add(progress.file);
                   downloadState.isDownloading = true;
@@ -128,8 +169,6 @@ async function createGerbilWorker(options = {}) {
                   downloadState.downloading.delete(progress.file);
                   downloadState.completed.add(progress.file);
                 }
-
-                // Only emit downloading status if actually downloading
                 if (downloadState.isDownloading) {
                   self.postMessage({
                     status: "downloading",
@@ -144,96 +183,229 @@ async function createGerbilWorker(options = {}) {
           );
 
           self.postMessage({ status: "loading", message: "Compiling shaders..." });
-          const warmupInputs = tokenizer("a");
-          await model.generate({ ...warmupInputs, max_new_tokens: 1 });
+          
+          // Warmup differs for vision vs text models
+          if (result.isVision) {
+            // Vision models need both text and vision warmup
+            // Text warmup first
+            const textWarmupInputs = result.tokenizer("hello");
+            await result.model.generate({ ...textWarmupInputs, max_new_tokens: 1 });
+            
+            // Vision warmup with synthetic image
+            self.postMessage({ status: "loading", message: "Warming up vision encoder..." });
+            try {
+              // Create a tiny 8x8 test image using OffscreenCanvas
+              const canvas = new OffscreenCanvas(8, 8);
+              const ctx = canvas.getContext("2d");
+              ctx.fillStyle = "red";
+              ctx.fillRect(0, 0, 8, 8);
+              const blob = await canvas.convertToBlob({ type: "image/png" });
+              const warmupImage = await RawImage.fromBlob(blob);
+              
+              // Process with vision pipeline
+              const warmupContent = [{ type: "image" }, { type: "text", text: "hi" }];
+              const warmupMessages = [{ role: "user", content: warmupContent }];
+              const warmupPrompt = result.processor.apply_chat_template(warmupMessages, { add_generation_prompt: true });
+              const warmupInputs = await result.processor(warmupImage, warmupPrompt, { add_special_tokens: false });
+              
+              // Run vision warmup generation
+              await result.model.generate({
+                ...warmupInputs,
+                max_new_tokens: 1,
+              });
+            } catch (warmupErr) {
+              console.warn("Vision warmup failed (non-fatal):", warmupErr);
+            }
+          } else {
+            const warmupInputs = result.tokenizer("a");
+            await result.model.generate({ ...warmupInputs, max_new_tokens: 1 });
+          }
 
-          self.postMessage({ status: "ready" });
+          self.postMessage({ status: "ready", isVision: result.isVision });
         } catch (error) {
           self.postMessage({ status: "error", error: error.message || String(error) });
         }
       }
 
       async function generate(data) {
-        const { messages, options = {} } = data;
+        const { messages, images = [], options = {} } = data;
         const { maxTokens = 256, temperature = 0.7, topP = 0.9, topK = 20, thinking = false } = options;
 
         try {
-          const { tokenizer, model } = await ModelPipeline.getInstance(ModelPipeline.modelId, {});
-
-          const inputs = tokenizer.apply_chat_template(messages, {
-            add_generation_prompt: true,
-            return_dict: true,
-            enable_thinking: thinking,
-          });
-
-          let state = "answering";
-          const [START_THINKING_TOKEN_ID, END_THINKING_TOKEN_ID] = tokenizer.encode(
-            "<think></think>",
-            { add_special_tokens: false }
-          );
-
-          let startTime = null;
-          let numTokens = 0;
-
-          // Token callback for state tracking (receives raw token IDs)
-          const tokenCallback = (tokens) => {
-            startTime ??= performance.now();
-            numTokens++;
-            
-            const tokenId = Number(tokens[0]);
-            if (tokenId === START_THINKING_TOKEN_ID) {
-              state = "thinking";
-            } else if (tokenId === END_THINKING_TOKEN_ID) {
-              state = "answering";
-            }
-          };
-
-          // Text callback for streaming (receives decoded text)
-          const streamCallback = (text) => {
-            const tps = startTime ? (numTokens / (performance.now() - startTime)) * 1000 : 0;
-            self.postMessage({ status: "token", text, state, numTokens, tps });
-          };
-
-          const streamer = new TextStreamer(tokenizer, {
-            skip_prompt: true,
-            skip_special_tokens: true,
-            callback_function: streamCallback,
-            token_callback_function: tokenCallback,
-          });
-
-          self.postMessage({ status: "start" });
-
-          const { past_key_values, sequences } = await model.generate({
-            ...inputs,
-            past_key_values: pastKeyValuesCache,
-            do_sample: temperature > 0,
-            temperature: temperature > 0 ? temperature : undefined,
-            top_p: topP,
-            top_k: topK,
-            max_new_tokens: maxTokens,
-            streamer,
-            stopping_criteria: stoppingCriteria,
-            return_dict_in_generate: true,
-          });
-
-          pastKeyValuesCache = past_key_values;
-
-          const endTime = performance.now();
-          const totalTime = startTime ? endTime - startTime : 0;
-          const decoded = tokenizer.batch_decode(sequences, { skip_special_tokens: true });
-
-          self.postMessage({
-            status: "complete",
-            text: decoded[0] || "",
-            numTokens,
-            totalTime,
-            tps: totalTime > 0 ? (numTokens / totalTime) * 1000 : 0,
-          });
+          const result = await ModelPipeline.getInstance(ModelPipeline.modelId, {});
+          
+          // Route to vision or text generation
+          if (result.isVision && images.length > 0) {
+            await generateVision(result, messages, images, options);
+          } else {
+            await generateText(result, messages, options);
+          }
         } catch (error) {
           self.postMessage({ status: "error", error: error.message || String(error) });
         }
       }
 
+      async function generateText(result, messages, options) {
+        const { maxTokens = 256, temperature = 0.7, topP = 0.9, topK = 20, thinking = false } = options;
+        const { tokenizer, model } = result;
+
+        const inputs = tokenizer.apply_chat_template(messages, {
+          add_generation_prompt: true,
+          return_dict: true,
+          enable_thinking: thinking,
+        });
+
+        let state = "answering";
+        const [START_THINKING_TOKEN_ID, END_THINKING_TOKEN_ID] = tokenizer.encode(
+          "<think></think>",
+          { add_special_tokens: false }
+        );
+
+        let startTime = null;
+        let numTokens = 0;
+
+        const tokenCallback = (tokens) => {
+          startTime ??= performance.now();
+          numTokens += 1;
+          const tokenId = Number(tokens[0]);
+          if (tokenId === START_THINKING_TOKEN_ID) state = "thinking";
+          else if (tokenId === END_THINKING_TOKEN_ID) state = "answering";
+        };
+
+        const streamCallback = (text) => {
+          const tps = startTime ? (numTokens / (performance.now() - startTime)) * 1000 : 0;
+          self.postMessage({ status: "token", text, state, numTokens, tps });
+        };
+
+        const streamer = new TextStreamer(tokenizer, {
+          skip_prompt: true,
+          skip_special_tokens: true,
+          callback_function: streamCallback,
+          token_callback_function: tokenCallback,
+        });
+
+        self.postMessage({ status: "start" });
+
+        const { past_key_values, sequences } = await model.generate({
+          ...inputs,
+          past_key_values: pastKeyValuesCache,
+          do_sample: temperature > 0,
+          temperature: temperature > 0 ? temperature : undefined,
+          top_p: topP,
+          top_k: topK,
+          max_new_tokens: maxTokens,
+          streamer,
+          stopping_criteria: stoppingCriteria,
+          return_dict_in_generate: true,
+        });
+
+        pastKeyValuesCache = past_key_values;
+
+        const endTime = performance.now();
+        const totalTime = startTime ? endTime - startTime : 0;
+        const decoded = tokenizer.batch_decode(sequences, { skip_special_tokens: true });
+
+        self.postMessage({
+          status: "complete",
+          text: decoded[0] || "",
+          numTokens,
+          totalTime,
+          tps: totalTime > 0 ? (numTokens / totalTime) * 1000 : 0,
+        });
+      }
+
+      async function generateVision(result, messages, images, options) {
+        const { maxTokens = 2048, temperature = 0.7, topP = 0.9, topK = 20 } = options;
+        const { processor, model, tokenizer } = result;
+
+        self.postMessage({ status: "progress", message: "Preparing vision request..." });
+
+        // Build message content with image placeholders and text
+        const lastMessage = messages[messages.length - 1];
+        const content = [];
+        for (const _ of images) {
+          content.push({ type: "image" });
+        }
+        content.push({ type: "text", text: lastMessage.content });
+
+        // For vision models, include a brief system instruction for concise responses
+        // Note: Vision processors handle system differently than text models
+        const visionMessages = [
+          { role: "system", content: "You are a helpful assistant. Be concise and direct in your responses." },
+          { role: "user", content }
+        ];
+
+        // Apply chat template with generation prompt
+        const chatPrompt = processor.apply_chat_template(visionMessages, {
+          add_generation_prompt: true
+        });
+
+        // Load images (handle both string URLs and { source: string } objects)
+        self.postMessage({ status: "progress", message: "Loading images..." });
+        const loadedImages = await Promise.all(
+          images.map(img => {
+            const url = typeof img === "string" ? img : img.source;
+            return RawImage.fromURL(url);
+          })
+        );
+        self.postMessage({ status: "progress", message: "Processing inputs..." });
+
+        // Process inputs
+        const inputs = await processor(
+          loadedImages.length === 1 ? loadedImages[0] : loadedImages,
+          chatPrompt,
+          { add_special_tokens: false }
+        );
+        self.postMessage({ status: "progress", message: "Generating response..." });
+
+        let startTime = null;
+        let numTokens = 0;
+
+        const streamCallback = (text) => {
+          startTime ??= performance.now();
+          numTokens += 1;
+          const tps = (numTokens / (performance.now() - startTime)) * 1000;
+          self.postMessage({ status: "token", text, state: "answering", numTokens, tps });
+        };
+
+        const streamer = new TextStreamer(tokenizer, {
+          skip_prompt: true,
+          skip_special_tokens: true,
+          callback_function: streamCallback,
+        });
+
+        self.postMessage({ status: "start" });
+
+        const outputs = await model.generate({
+          ...inputs,
+          max_new_tokens: maxTokens,
+          do_sample: temperature > 0,
+          temperature: temperature > 0 ? temperature : undefined,
+          top_p: topP,
+          top_k: topK,
+          streamer,
+          stopping_criteria: stoppingCriteria,
+        });
+
+        // Decode output (skip prompt)
+        const inputLength = inputs.input_ids.dims?.at(-1) || 0;
+        const decoded = processor.batch_decode(
+          outputs.slice(null, [inputLength, null]),
+          { skip_special_tokens: true }
+        );
+
+        const endTime = performance.now();
+        const totalTime = startTime ? endTime - startTime : 0;
+
+        self.postMessage({
+          status: "complete",
+          text: decoded[0] || "",
+          numTokens,
+          totalTime,
+          tps: totalTime > 0 ? (numTokens / totalTime) * 1000 : 0,
+        });
+      }
+
       self.addEventListener("message", async (e) => {
         const { type, ...data } = e.data;
         switch (type) {
@@ -303,30 +475,34 @@ async function createGerbilWorker(options = {}) {
 			reject(new Error(error));
 		};
 		const gerbilWorker = {
-			generate: (prompt, options$1 = {}) => {
-				return new Promise((res, rej) => {
-					currentResolve = res;
-					currentReject = rej;
-					const messages = [{
-						role: "system",
-						content: options$1.system || "You are a helpful assistant."
-					}, {
-						role: "user",
-						content: prompt
-					}];
-					worker.postMessage({
-						type: "generate",
-						messages,
-						options: {
-							maxTokens: options$1.maxTokens ?? 256,
-							temperature: options$1.temperature ?? .7,
-							topP: options$1.topP ?? .9,
-							topK: options$1.topK ?? 20,
-							thinking: options$1.thinking ?? false
-						}
-					});
+			generate: (prompt, options$1 = {}) => new Promise((res, rej) => {
+				currentResolve = res;
+				currentReject = rej;
+				const system = options$1.system || "You are a helpful assistant.";
+				const messages = options$1.history ? [{
+					role: "system",
+					content: system
+				}, ...options$1.history] : [{
+					role: "system",
+					content: system
+				}, {
+					role: "user",
+					content: prompt
+				}];
+				if (options$1.history) worker.postMessage({ type: "reset" });
+				worker.postMessage({
+					type: "generate",
+					messages,
+					images: options$1.images || [],
+					options: {
+						maxTokens: options$1.maxTokens ?? (options$1.images?.length ? 2048 : 256),
+						temperature: options$1.temperature ?? .7,
+						topP: options$1.topP ?? .9,
+						topK: options$1.topK ?? 20,
+						thinking: options$1.thinking ?? false
+					}
 				});
-			},
+			}),
 			interrupt: () => {
 				worker.postMessage({ type: "interrupt" });
 			},
@@ -383,6 +559,7 @@ function useChat(options = {}) {
 	const [error, setError] = useState(null);
 	const [isReady, setIsReady] = useState(false);
 	const [shouldLoad, setShouldLoad] = useState(autoLoad);
+	const [attachedImages, setAttachedImages] = useState([]);
 	const workerRef = useRef(null);
 	const messageIdRef = useRef(0);
 	const mountedRef = useRef(true);
@@ -455,23 +632,34 @@ function useChat(options = {}) {
 			setCurrentResponse("");
 			setThinking("");
 		}
-		return () => {};
 	}, [
 		isGenerating,
 		currentResponse,
 		thinking
 	]);
 	const pendingMessageRef = useRef(null);
-	const handleSubmit = useCallback((e) => {
-		e?.preventDefault?.();
-		if (!input.trim() || isGenerating) return;
+	const pendingImagesRef = useRef([]);
+	const attachImage = useCallback((imageUrl) => {
+		setAttachedImages((imgs) => [...imgs, imageUrl]);
+	}, []);
+	const removeImage = useCallback((index) => {
+		setAttachedImages((imgs) => imgs.filter((_, i) => i !== index));
+	}, []);
+	const clearImages = useCallback(() => {
+		setAttachedImages([]);
+	}, []);
+	const sendMessageWithImages = useCallback((text, images) => {
+		if (!text.trim() || isGenerating) return;
+		messageIdRef.current += 1;
 		const userMessage = {
-			id: `msg-${++messageIdRef.current}`,
+			id: `msg-${messageIdRef.current}`,
 			role: "user",
-			content: input.trim()
+			content: text.trim(),
+			images: images.length > 0 ? images : void 0
 		};
+		messageIdRef.current += 1;
 		const assistantMessage = {
-			id: `msg-${++messageIdRef.current}`,
+			id: `msg-${messageIdRef.current}`,
 			role: "assistant",
 			content: ""
 		};
@@ -480,23 +668,23 @@ function useChat(options = {}) {
 			userMessage,
 			assistantMessage
 		]);
-		setInput("");
 		setCurrentResponse("");
 		setThinking("");
 		if (!workerRef.current) {
-			pendingMessageRef.current = userMessage.content;
+			pendingMessageRef.current = text.trim();
+			pendingImagesRef.current = images;
 			load();
 			return;
 		}
 		setIsGenerating(true);
-		workerRef.current.generate(userMessage.content, {
+		workerRef.current.generate(text.trim(), {
 			system,
 			thinking: enableThinking,
-			maxTokens,
-			temperature
+			maxTokens: images.length > 0 ? Math.max(maxTokens, 2048) : maxTokens,
+			temperature,
+			images: images.length > 0 ? images : void 0
 		});
 	}, [
-		input,
 		isGenerating,
 		system,
 		enableThinking,
@@ -504,19 +692,36 @@ function useChat(options = {}) {
 		temperature,
 		load
 	]);
+	const handleSubmit = useCallback((e) => {
+		e?.preventDefault?.();
+		if (!input.trim() || isGenerating) return;
+		sendMessageWithImages(input, attachedImages);
+		setInput("");
+		setAttachedImages([]);
+	}, [
+		input,
+		isGenerating,
+		attachedImages,
+		sendMessageWithImages
+	]);
+	const sendWithImages = useCallback((text, images) => {
+		sendMessageWithImages(text, images);
+	}, [sendMessageWithImages]);
 	useEffect(() => {
 		if (isReady && pendingMessageRef.current && workerRef.current) {
 			const pendingContent = pendingMessageRef.current;
+			const pendingImages = pendingImagesRef.current;
 			pendingMessageRef.current = null;
+			pendingImagesRef.current = [];
 			setIsGenerating(true);
 			workerRef.current.generate(pendingContent, {
 				system,
 				thinking: enableThinking,
-				maxTokens,
-				temperature
+				maxTokens: pendingImages.length > 0 ? Math.max(maxTokens, 2048) : maxTokens,
+				temperature,
+				images: pendingImages.length > 0 ? pendingImages : void 0
 			});
 		}
-		return () => {};
 	}, [
 		isReady,
 		system,
@@ -533,6 +738,7 @@ function useChat(options = {}) {
 		setMessages([]);
 		setCurrentResponse("");
 		setThinking("");
+		setAttachedImages([]);
 	}, []);
 	return {
 		messages: messages.map((m, i) => {
@@ -555,7 +761,12 @@ function useChat(options = {}) {
 		tps,
 		isReady,
 		error,
-		load
+		load,
+		attachedImages,
+		attachImage,
+		removeImage,
+		clearImages,
+		sendWithImages
 	};
 }
 /**
@@ -597,6 +808,7 @@ function useCompletion(options = {}) {
 	const resolveRef = useRef(null);
 	const rejectRef = useRef(null);
 	const pendingPromptRef = useRef(null);
+	const pendingImagesRef = useRef(void 0);
 	const mountedRef = useRef(true);
 	const load = useCallback(() => {
 		if (workerRef.current || isLoading) return;
@@ -656,7 +868,7 @@ function useCompletion(options = {}) {
 			workerRef.current?.terminate();
 		};
 	}, [model, shouldLoad]);
-	const complete = useCallback((prompt) => {
+	const complete = useCallback((prompt, completeOptions) => {
 		return new Promise((resolve, reject) => {
 			setCompletion("");
 			setThinking("");
@@ -664,6 +876,7 @@ function useCompletion(options = {}) {
 			rejectRef.current = reject;
 			if (!workerRef.current) {
 				pendingPromptRef.current = prompt;
+				pendingImagesRef.current = completeOptions?.images;
 				load();
 				return;
 			}
@@ -672,7 +885,8 @@ function useCompletion(options = {}) {
 				system,
 				thinking: enableThinking,
 				maxTokens,
-				temperature
+				temperature,
+				images: completeOptions?.images
 			});
 		});
 	}, [
@@ -685,16 +899,18 @@ function useCompletion(options = {}) {
 	useEffect(() => {
 		if (isReady && pendingPromptRef.current && workerRef.current) {
 			const pendingPrompt = pendingPromptRef.current;
+			const pendingImages = pendingImagesRef.current;
 			pendingPromptRef.current = null;
+			pendingImagesRef.current = void 0;
 			setIsGenerating(true);
 			workerRef.current.generate(pendingPrompt, {
 				system,
 				thinking: enableThinking,
 				maxTokens,
-				temperature
+				temperature,
+				images: pendingImages
 			});
 		}
-		return () => {};
 	}, [
 		isReady,
 		system,
@@ -719,6 +935,1414 @@ function useCompletion(options = {}) {
 		load
 	};
 }
+/** Kokoro voice definitions (24kHz, high quality) */
+const KOKORO_BROWSER_VOICES = [
+	{
+		id: "af_heart",
+		name: "Heart",
+		gender: "female",
+		language: "en-us",
+		description: "American female, highest quality (Grade A)"
+	},
+	{
+		id: "af_bella",
+		name: "Bella",
+		gender: "female",
+		language: "en-us",
+		description: "American female, warm and friendly (Grade A-)"
+	},
+	{
+		id: "af_nicole",
+		name: "Nicole",
+		gender: "female",
+		language: "en-us",
+		description: "American female, soft and gentle"
+	},
+	{
+		id: "af_sarah",
+		name: "Sarah",
+		gender: "female",
+		language: "en-us",
+		description: "American female, clear and professional"
+	},
+	{
+		id: "af_sky",
+		name: "Sky",
+		gender: "female",
+		language: "en-us",
+		description: "American female, young and energetic"
+	},
+	{
+		id: "af_alloy",
+		name: "Alloy",
+		gender: "female",
+		language: "en-us",
+		description: "American female"
+	},
+	{
+		id: "af_aoede",
+		name: "Aoede",
+		gender: "female",
+		language: "en-us",
+		description: "American female, mythical"
+	},
+	{
+		id: "af_jessica",
+		name: "Jessica",
+		gender: "female",
+		language: "en-us",
+		description: "American female"
+	},
+	{
+		id: "af_kore",
+		name: "Kore",
+		gender: "female",
+		language: "en-us",
+		description: "American female"
+	},
+	{
+		id: "af_nova",
+		name: "Nova",
+		gender: "female",
+		language: "en-us",
+		description: "American female"
+	},
+	{
+		id: "af_river",
+		name: "River",
+		gender: "female",
+		language: "en-us",
+		description: "American female"
+	},
+	{
+		id: "am_fenrir",
+		name: "Fenrir",
+		gender: "male",
+		language: "en-us",
+		description: "American male, best quality"
+	},
+	{
+		id: "am_michael",
+		name: "Michael",
+		gender: "male",
+		language: "en-us",
+		description: "American male, warm and friendly"
+	},
+	{
+		id: "am_adam",
+		name: "Adam",
+		gender: "male",
+		language: "en-us",
+		description: "American male"
+	},
+	{
+		id: "am_echo",
+		name: "Echo",
+		gender: "male",
+		language: "en-us",
+		description: "American male"
+	},
+	{
+		id: "am_eric",
+		name: "Eric",
+		gender: "male",
+		language: "en-us",
+		description: "American male"
+	},
+	{
+		id: "am_liam",
+		name: "Liam",
+		gender: "male",
+		language: "en-us",
+		description: "American male"
+	},
+	{
+		id: "am_onyx",
+		name: "Onyx",
+		gender: "male",
+		language: "en-us",
+		description: "American male"
+	},
+	{
+		id: "am_puck",
+		name: "Puck",
+		gender: "male",
+		language: "en-us",
+		description: "American male"
+	},
+	{
+		id: "am_santa",
+		name: "Santa",
+		gender: "male",
+		language: "en-us",
+		description: "American male, festive"
+	},
+	{
+		id: "bf_emma",
+		name: "Emma",
+		gender: "female",
+		language: "en-gb",
+		description: "British female, elegant and clear"
+	},
+	{
+		id: "bf_isabella",
+		name: "Isabella",
+		gender: "female",
+		language: "en-gb",
+		description: "British female, sophisticated"
+	},
+	{
+		id: "bf_alice",
+		name: "Alice",
+		gender: "female",
+		language: "en-gb",
+		description: "British female"
+	},
+	{
+		id: "bf_lily",
+		name: "Lily",
+		gender: "female",
+		language: "en-gb",
+		description: "British female"
+	},
+	{
+		id: "bm_george",
+		name: "George",
+		gender: "male",
+		language: "en-gb",
+		description: "British male, distinguished"
+	},
+	{
+		id: "bm_lewis",
+		name: "Lewis",
+		gender: "male",
+		language: "en-gb",
+		description: "British male, friendly"
+	},
+	{
+		id: "bm_daniel",
+		name: "Daniel",
+		gender: "male",
+		language: "en-gb",
+		description: "British male"
+	},
+	{
+		id: "bm_fable",
+		name: "Fable",
+		gender: "male",
+		language: "en-gb",
+		description: "British male"
+	}
+];
+/** Supertonic voice definitions (44.1kHz, faster) */
+const SUPERTONIC_BROWSER_VOICES = [
+	{
+		id: "F1",
+		name: "Female 1",
+		gender: "female",
+		language: "en",
+		description: "Female voice 1 - Clear and natural"
+	},
+	{
+		id: "F2",
+		name: "Female 2",
+		gender: "female",
+		language: "en",
+		description: "Female voice 2 - Warm and expressive"
+	},
+	{
+		id: "M1",
+		name: "Male 1",
+		gender: "male",
+		language: "en",
+		description: "Male voice 1 - Deep and confident"
+	},
+	{
+		id: "M2",
+		name: "Male 2",
+		gender: "male",
+		language: "en",
+		description: "Male voice 2 - Friendly and casual"
+	}
+];
+/** TTS model configuration */
+const TTS_MODELS = {
+	"kokoro-82m": {
+		repo: "onnx-community/Kokoro-82M-v1.0-ONNX",
+		defaultVoice: "af_heart",
+		sampleRate: 24e3,
+		voices: KOKORO_BROWSER_VOICES
+	},
+	"supertonic-66m": {
+		repo: "onnx-community/Supertonic-TTS-ONNX",
+		defaultVoice: "F1",
+		sampleRate: 44100,
+		voices: SUPERTONIC_BROWSER_VOICES
+	}
+};
+/**
+* React hook for text-to-speech with Web Audio API playback
+*
+* Supports both Kokoro (24kHz, high quality) and Supertonic (44.1kHz, faster).
+*
+* @example
+* ```tsx
+* import { useSpeech } from "@tryhamster/gerbil/browser";
+*
+* function App() {
+*   // Default: Kokoro TTS
+*   const { speak, stop, isLoading, isSpeaking, listVoices, setVoice } = useSpeech();
+*
+*   // Or use Supertonic (44.1kHz, faster)
+*   // const { speak, listVoices } = useSpeech({ model: "supertonic-66m" });
+*
+*   if (isLoading) return <div>Loading TTS...</div>;
+*
+*   return (
+*     <div>
+*       <select onChange={e => setVoice(e.target.value)}>
+*         {listVoices().map(v => (
+*           <option key={v.id} value={v.id}>{v.name}</option>
+*         ))}
+*       </select>
+*       <button onClick={() => speak("Hello world!")}>
+*         {isSpeaking ? "Speaking..." : "Speak"}
+*       </button>
+*       {isSpeaking && <button onClick={stop}>Stop</button>}
+*     </div>
+*   );
+* }
+* ```
+*/
+function useSpeech(options = {}) {
+	const React = globalThis.React;
+	if (!React) throw new Error("useSpeech requires React. Import React before using this hook.");
+	const { useState, useEffect, useRef, useCallback } = React;
+	const { model: modelId = "kokoro-82m", speed: defaultSpeed = 1, autoLoad = false, onReady, onError, onStart, onEnd } = options;
+	const modelConfig = TTS_MODELS[modelId];
+	const defaultVoice = options.voice || modelConfig.defaultVoice;
+	const [isLoading, setIsLoading] = useState(autoLoad);
+	const [loadingProgress, setLoadingProgress] = useState(null);
+	const [isSpeaking, setIsSpeaking] = useState(false);
+	const [isReady, setIsReady] = useState(false);
+	const [error, setError] = useState(null);
+	const [shouldLoad, setShouldLoad] = useState(autoLoad);
+	const [currentVoice, setCurrentVoice] = useState(defaultVoice);
+	const [currentSpeed, setCurrentSpeed] = useState(defaultSpeed);
+	const ttsRef = useRef(null);
+	const voiceEmbeddingsRef = useRef(/* @__PURE__ */ new Map());
+	const audioContextRef = useRef(null);
+	const sourceNodeRef = useRef(null);
+	const mountedRef = useRef(true);
+	const modelIdRef = useRef(modelId);
+	const listVoices = useCallback(() => {
+		return modelConfig.voices;
+	}, [modelConfig.voices]);
+	const load = useCallback(() => {
+		if (ttsRef.current || isLoading) return;
+		setIsLoading(true);
+		setShouldLoad(true);
+	}, [isLoading]);
+	useEffect(() => {
+		if (!shouldLoad) return;
+		mountedRef.current = true;
+		modelIdRef.current = modelId;
+		const initTTS = async () => {
+			try {
+				const isSupertonic = modelId === "supertonic-66m";
+				const config = TTS_MODELS[modelId];
+				setLoadingProgress({
+					status: "loading",
+					message: `Loading ${isSupertonic ? "Supertonic" : "Kokoro"} TTS...`
+				});
+				if (isSupertonic) {
+					const { pipeline } = await import("@huggingface/transformers");
+					const tts = await pipeline("text-to-speech", config.repo, {
+						device: "webgpu",
+						progress_callback: (progress) => {
+							if (!mountedRef.current) return;
+							if (progress.status === "progress" && progress.file) setLoadingProgress({
+								status: "downloading",
+								file: progress.file,
+								progress: Math.round(progress.progress || 0)
+							});
+						}
+					});
+					if (!mountedRef.current) return;
+					const voicesUrl = `https://huggingface.co/${config.repo}/resolve/main/voices/`;
+					const embeddingsMap = /* @__PURE__ */ new Map();
+					await Promise.all(config.voices.map(async (voice) => {
+						try {
+							const response = await fetch(`${voicesUrl}${voice.id}.bin`);
+							if (response.ok) {
+								const buffer = await response.arrayBuffer();
+								embeddingsMap.set(voice.id, new Float32Array(buffer));
+							}
+						} catch (e) {
+							console.warn(`Failed to load voice embedding for ${voice.id}:`, e);
+						}
+					}));
+					if (!mountedRef.current) return;
+					try {
+						await tts("Hello", {
+							speaker_embeddings: new Float32Array(12928),
+							num_inference_steps: 1,
+							speed: 1
+						});
+					} catch (e) {
+						console.warn("Supertonic warmup failed:", e);
+					}
+					voiceEmbeddingsRef.current = embeddingsMap;
+					ttsRef.current = {
+						type: "supertonic",
+						pipeline: tts,
+						config
+					};
+				} else {
+					const { KokoroTTS } = await import("kokoro-js");
+					const tts = await KokoroTTS.from_pretrained(config.repo, {
+						dtype: "fp32",
+						progress_callback: (progress) => {
+							if (!mountedRef.current) return;
+							if (progress.status === "progress" && progress.file) setLoadingProgress({
+								status: "downloading",
+								file: progress.file,
+								progress: Math.round(progress.progress || 0)
+							});
+						}
+					});
+					if (!mountedRef.current) return;
+					ttsRef.current = {
+						type: "kokoro",
+						instance: tts,
+						config
+					};
+				}
+				setIsLoading(false);
+				setIsReady(true);
+				setLoadingProgress({ status: "ready" });
+				onReady?.();
+			} catch (err) {
+				if (!mountedRef.current) return;
+				const errorMsg = err instanceof Error ? err.message : String(err);
+				setError(errorMsg);
+				setIsLoading(false);
+				setLoadingProgress({
+					status: "error",
+					error: errorMsg
+				});
+				onError?.(errorMsg);
+			}
+		};
+		initTTS();
+		return () => {
+			mountedRef.current = false;
+		};
+	}, [
+		shouldLoad,
+		modelId,
+		onReady,
+		onError
+	]);
+	useEffect(() => {
+		return () => {
+			try {
+				sourceNodeRef.current?.stop();
+			} catch {}
+			try {
+				if (audioContextRef.current && audioContextRef.current.state !== "closed") audioContextRef.current.close();
+			} catch {}
+		};
+	}, []);
+	return {
+		speak: useCallback(async (text, opts) => {
+			const voice = opts?.voice || currentVoice;
+			const speed = opts?.speed || currentSpeed;
+			if (!ttsRef.current) {
+				load();
+				return;
+			}
+			try {
+				setIsSpeaking(true);
+				onStart?.();
+				let audioData;
+				let sampleRate;
+				const ttsBackend = ttsRef.current;
+				if (ttsBackend.type === "supertonic") {
+					const config = ttsBackend.config;
+					if (!config.voices.find((v) => v.id === voice)) {
+						const validVoices = config.voices.map((v) => v.id).join(", ");
+						throw new Error(`Voice "${voice}" not found. Should be one of: ${validVoices}.`);
+					}
+					let speakerEmbedding = voiceEmbeddingsRef.current.get(voice);
+					if (!speakerEmbedding) try {
+						const voiceUrl = `https://huggingface.co/${config.repo}/resolve/main/voices/${voice}.bin`;
+						const response = await fetch(voiceUrl);
+						if (response.ok) {
+							const buffer = await response.arrayBuffer();
+							speakerEmbedding = new Float32Array(buffer);
+							voiceEmbeddingsRef.current.set(voice, speakerEmbedding);
+						} else throw new Error(`Failed to load voice: ${response.status}`);
+					} catch {
+						speakerEmbedding = new Float32Array(12928).fill(.1);
+						voiceEmbeddingsRef.current.set(voice, speakerEmbedding);
+					}
+					const result = await ttsBackend.pipeline(text, {
+						speaker_embeddings: speakerEmbedding,
+						speed
+					});
+					audioData = result.audio;
+					sampleRate = result.sampling_rate;
+				} else {
+					const config = ttsBackend.config;
+					if (!config.voices.find((v) => v.id === voice)) {
+						const validVoices = config.voices.map((v) => v.id).join(", ");
+						throw new Error(`Voice "${voice}" not found. Should be one of: ${validVoices}.`);
+					}
+					const result = await ttsBackend.instance.generate(text, {
+						voice,
+						speed
+					});
+					audioData = result.audio;
+					sampleRate = result.sampling_rate;
+				}
+				if (!mountedRef.current) return;
+				if (!audioContextRef.current || audioContextRef.current.state === "closed") audioContextRef.current = new AudioContext();
+				const audioContext = audioContextRef.current;
+				if (audioContext.state === "suspended") await audioContext.resume();
+				const audioBuffer = audioContext.createBuffer(1, audioData.length, sampleRate);
+				const channelData = new Float32Array(audioData);
+				audioBuffer.copyToChannel(channelData, 0);
+				if (sourceNodeRef.current) {
+					sourceNodeRef.current.stop();
+					sourceNodeRef.current.disconnect();
+				}
+				const sourceNode = audioContext.createBufferSource();
+				sourceNode.buffer = audioBuffer;
+				sourceNode.connect(audioContext.destination);
+				sourceNode.onended = () => {
+					if (mountedRef.current) {
+						setIsSpeaking(false);
+						onEnd?.();
+					}
+				};
+				sourceNodeRef.current = sourceNode;
+				sourceNode.start();
+			} catch (err) {
+				if (!mountedRef.current) return;
+				const errorMsg = err instanceof Error ? err.message : String(err);
+				setError(errorMsg);
+				setIsSpeaking(false);
+				onError?.(errorMsg);
+			}
+		}, [
+			currentVoice,
+			currentSpeed,
+			load,
+			onStart,
+			onEnd,
+			onError
+		]),
+		stop: useCallback(() => {
+			if (sourceNodeRef.current) {
+				sourceNodeRef.current.stop();
+				sourceNodeRef.current.disconnect();
+				sourceNodeRef.current = null;
+			}
+			setIsSpeaking(false);
+		}, []),
+		isLoading,
+		loadingProgress,
+		isSpeaking,
+		isReady,
+		load,
+		error,
+		listVoices,
+		currentVoice,
+		setVoice: useCallback((voiceId) => {
+			if (modelConfig.voices.find((v) => v.id === voiceId)) setCurrentVoice(voiceId);
+			else console.warn(`Voice "${voiceId}" not valid for ${modelId}. Available: ${modelConfig.voices.map((v) => v.id).join(", ")}`);
+		}, [modelConfig.voices, modelId]),
+		currentSpeed,
+		setSpeed: useCallback((speed) => {
+			setCurrentSpeed(Math.max(.5, Math.min(2, speed)));
+		}, []),
+		currentModel: modelId,
+		sampleRate: modelConfig.sampleRate
+	};
+}
+/**
+* Play audio from Float32Array using Web Audio API
+*
+* @example
+* ```ts
+* import { playAudio } from "@tryhamster/gerbil/browser";
+*
+* const audio = new Float32Array([...]); // TTS output
+* const controller = await playAudio(audio, 24000);
+*
+* // Stop playback
+* controller.stop();
+* ```
+*/
+async function playAudio(audio, sampleRate = 24e3) {
+	const audioContext = new AudioContext();
+	if (audioContext.state === "suspended") await audioContext.resume();
+	const audioBuffer = audioContext.createBuffer(1, audio.length, sampleRate);
+	const channelData = new Float32Array(audio);
+	audioBuffer.copyToChannel(channelData, 0);
+	const sourceNode = audioContext.createBufferSource();
+	sourceNode.buffer = audioBuffer;
+	sourceNode.connect(audioContext.destination);
+	const onEnded = new Promise((resolve) => {
+		sourceNode.onended = () => {
+			audioContext.close();
+			resolve();
+		};
+	});
+	sourceNode.start();
+	return {
+		stop: () => {
+			sourceNode.stop();
+			audioContext.close();
+		},
+		onEnded
+	};
+}
+/**
+* Create a reusable audio player for streaming TTS
+*
+* @example
+* ```ts
+* import { createAudioPlayer } from "@tryhamster/gerbil/browser";
+*
+* const player = createAudioPlayer(24000);
+*
+* // Queue audio chunks as they arrive
+* player.queue(chunk1);
+* player.queue(chunk2);
+*
+* // Stop and clear
+* player.stop();
+* ```
+*/
+function createAudioPlayer(sampleRate = 24e3) {
+	let audioContext = null;
+	let nextStartTime = 0;
+	let isActive = false;
+	const ensureContext = async () => {
+		if (!audioContext) audioContext = new AudioContext();
+		if (audioContext.state === "suspended") await audioContext.resume();
+		return audioContext;
+	};
+	return {
+		queue: async (audio) => {
+			const ctx = await ensureContext();
+			isActive = true;
+			const buffer = ctx.createBuffer(1, audio.length, sampleRate);
+			const channelData = new Float32Array(audio);
+			buffer.copyToChannel(channelData, 0);
+			const source = ctx.createBufferSource();
+			source.buffer = buffer;
+			source.connect(ctx.destination);
+			const startTime = Math.max(ctx.currentTime, nextStartTime);
+			source.start(startTime);
+			nextStartTime = startTime + buffer.duration;
+			source.onended = () => {
+				if (ctx.currentTime >= nextStartTime - .1) isActive = false;
+			};
+		},
+		stop: () => {
+			isActive = false;
+			nextStartTime = 0;
+			if (audioContext) {
+				audioContext.close();
+				audioContext = null;
+			}
+		},
+		isPlaying: () => isActive
+	};
+}
+/**
+* React hook for voice input with browser microphone
+*
+* Uses MediaRecorder to capture audio and Whisper for transcription.
+* Supports both one-shot and streaming transcription modes.
+*
+* @example Basic usage (one-shot)
+* ```tsx
+* function VoiceInput() {
+*   const { startRecording, stopRecording, isRecording, transcript } = useVoiceInput({
+*     onTranscript: (text) => console.log("User said:", text),
+*   });
+*
+*   return (
+*     <button onClick={isRecording ? stopRecording : startRecording}>
+*       {isRecording ? "Stop" : "Record"}
+*     </button>
+*   );
+* }
+* ```
+*
+* @example Streaming transcription (real-time)
+* ```tsx
+* function LiveTranscription() {
+*   const { startRecording, stopRecording, isRecording, transcript, streamingChunk } = useVoiceInput({
+*     streaming: true,           // Enable streaming mode
+*     chunkDuration: 1500,       // Transcribe every 1.5 seconds (default)
+*     onChunk: (text, idx) => console.log(`Chunk ${idx}: ${text}`),
+*   });
+*
+*   return (
+*     <div>
+*       <button onClick={isRecording ? stopRecording : startRecording}>
+*         {isRecording ? "Stop" : "Start Live Transcription"}
+*       </button>
+*       <p>Current chunk: {streamingChunk}</p>
+*       <p>Full transcript: {transcript}</p>
+*     </div>
+*   );
+* }
+* ```
+*/
+function useVoiceInput(options = {}) {
+	const React = globalThis.React;
+	if (!React) throw new Error("useVoiceInput requires React. Import React before using this hook.");
+	const { useState, useEffect, useRef, useCallback } = React;
+	const { model = "whisper-tiny.en", autoLoad = false, onReady, onTranscript, onError, onProgress, streaming = false, chunkDuration = 1500, onChunk } = options;
+	const [isLoading, setIsLoading] = useState(autoLoad);
+	const [loadingProgress, setLoadingProgress] = useState(null);
+	const [isReady, setIsReady] = useState(false);
+	const [isRecording, setIsRecording] = useState(false);
+	const [isTranscribing, setIsTranscribing] = useState(false);
+	const [transcript, setTranscript] = useState("");
+	const [streamingChunk, setStreamingChunk] = useState("");
+	const [chunkCount, setChunkCount] = useState(0);
+	const [error, setError] = useState(null);
+	const [shouldLoad, setShouldLoad] = useState(autoLoad);
+	const sttRef = useRef(null);
+	const mediaRecorderRef = useRef(null);
+	const audioChunksRef = useRef([]);
+	const streamRef = useRef(null);
+	const mountedRef = useRef(true);
+	const streamingIntervalRef = useRef(null);
+	const pendingChunksRef = useRef([]);
+	const fullTranscriptRef = useRef("");
+	useEffect(() => {
+		if (!shouldLoad || isReady) return;
+		let cancelled = false;
+		const loadModel = async () => {
+			try {
+				setIsLoading(true);
+				setLoadingProgress({
+					status: "loading",
+					message: "Loading STT model..."
+				});
+				onProgress?.({
+					status: "loading",
+					message: "Loading STT model..."
+				});
+				const { WhisperSTT } = await import("../stt-KzSoNvwI.mjs");
+				if (cancelled || !mountedRef.current) return;
+				const stt = new WhisperSTT(model);
+				await stt.load({ onProgress: (p) => {
+					if (!mountedRef.current) return;
+					const progress = {
+						status: p.progress !== void 0 ? "downloading" : "loading",
+						message: p.status,
+						progress: p.progress,
+						file: p.file
+					};
+					setLoadingProgress(progress);
+					onProgress?.(progress);
+				} });
+				if (cancelled || !mountedRef.current) {
+					stt.dispose();
+					return;
+				}
+				sttRef.current = stt;
+				setIsReady(true);
+				setIsLoading(false);
+				setLoadingProgress({ status: "ready" });
+				onProgress?.({ status: "ready" });
+				onReady?.();
+			} catch (e) {
+				if (!mountedRef.current) return;
+				const errMsg = e.message || "Failed to load STT model";
+				setError(errMsg);
+				setIsLoading(false);
+				setLoadingProgress({
+					status: "error",
+					message: errMsg
+				});
+				onProgress?.({
+					status: "error",
+					message: errMsg
+				});
+				onError?.(errMsg);
+			}
+		};
+		loadModel();
+		return () => {
+			cancelled = true;
+		};
+	}, [
+		shouldLoad,
+		isReady,
+		model,
+		onReady,
+		onError,
+		onProgress
+	]);
+	useEffect(() => {
+		mountedRef.current = true;
+		return () => {
+			mountedRef.current = false;
+			if (sttRef.current) sttRef.current.dispose();
+			if (streamRef.current) for (const track of streamRef.current.getTracks()) track.stop();
+		};
+	}, []);
+	const load = useCallback(() => {
+		if (!shouldLoad && !isReady && !isLoading) setShouldLoad(true);
+	}, [
+		shouldLoad,
+		isReady,
+		isLoading
+	]);
+	const blobToFloat32 = useCallback(async (blob) => {
+		const audioContext = new AudioContext({ sampleRate: 16e3 });
+		const arrayBuffer = await blob.arrayBuffer();
+		const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
+		const channelData = audioBuffer.getChannelData(0);
+		if (audioBuffer.sampleRate !== 16e3) {
+			const ratio = 16e3 / audioBuffer.sampleRate;
+			const newLength = Math.round(channelData.length * ratio);
+			const resampled = new Float32Array(newLength);
+			for (let i = 0; i < newLength; i++) {
+				const srcIndex = i / ratio;
+				const floor = Math.floor(srcIndex);
+				const ceil = Math.min(floor + 1, channelData.length - 1);
+				const t = srcIndex - floor;
+				resampled[i] = channelData[floor] * (1 - t) + channelData[ceil] * t;
+			}
+			audioContext.close();
+			return resampled;
+		}
+		audioContext.close();
+		return new Float32Array(channelData);
+	}, []);
+	const transcribe = useCallback(async (audio) => {
+		if (!sttRef.current) {
+			if (!shouldLoad) {
+				setShouldLoad(true);
+				throw new Error("STT model not loaded. Loading now, please try again.");
+			}
+			throw new Error("STT model not loaded");
+		}
+		setIsTranscribing(true);
+		try {
+			let text = (await sttRef.current.transcribe(audio)).text.trim();
+			if (text === "[BLANK_AUDIO]" || text === "(blank audio)" || text === "[BLANK AUDIO]") text = "";
+			setTranscript(text);
+			onTranscript?.(text);
+			return text;
+		} finally {
+			if (mountedRef.current) setIsTranscribing(false);
+		}
+	}, [shouldLoad, onTranscript]);
+	const processedSamplesRef = useRef(0);
+	const transcribeChunk = useCallback(async (chunkIdx) => {
+		if (!sttRef.current || audioChunksRef.current.length === 0) return "";
+		try {
+			const audioData = await blobToFloat32(new Blob(audioChunksRef.current, { type: "audio/webm" }));
+			const newSamplesStart = processedSamplesRef.current;
+			const totalSamples = audioData.length;
+			if (totalSamples - newSamplesStart < 8e3) return "";
+			const newAudio = audioData.slice(newSamplesStart);
+			processedSamplesRef.current = totalSamples;
+			let text = (await sttRef.current.transcribe(newAudio)).text.trim();
+			if (text === "[BLANK_AUDIO]" || text === "(blank audio)" || text === "[BLANK AUDIO]") text = "";
+			if (text && mountedRef.current) {
+				setStreamingChunk(text);
+				onChunk?.(text, chunkIdx);
+			}
+			return text;
+		} catch {
+			return "";
+		}
+	}, [blobToFloat32, onChunk]);
+	return {
+		startRecording: useCallback(async () => {
+			if (isRecording) return;
+			try {
+				if (streaming && !sttRef.current) {
+					if (!shouldLoad) setShouldLoad(true);
+					setIsLoading(true);
+					const { WhisperSTT } = await import("../stt-KzSoNvwI.mjs");
+					const stt = new WhisperSTT(model);
+					await stt.load({ onProgress: (p) => {
+						if (mountedRef.current) {
+							const progress = {
+								status: p.status === "downloading" ? "downloading" : p.status === "ready" ? "ready" : "loading",
+								message: p.status,
+								progress: p.progress,
+								file: p.file
+							};
+							setLoadingProgress(progress);
+							onProgress?.(progress);
+						}
+					} });
+					if (!mountedRef.current) {
+						stt.dispose();
+						return;
+					}
+					sttRef.current = stt;
+					setIsReady(true);
+					setIsLoading(false);
+					setLoadingProgress({ status: "ready" });
+					onProgress?.({ status: "ready" });
+					onReady?.();
+				}
+				const stream = await navigator.mediaDevices.getUserMedia({ audio: {
+					sampleRate: 16e3,
+					channelCount: 1,
+					echoCancellation: true,
+					noiseSuppression: true
+				} });
+				streamRef.current = stream;
+				audioChunksRef.current = [];
+				pendingChunksRef.current = [];
+				fullTranscriptRef.current = "";
+				processedSamplesRef.current = 0;
+				setTranscript("");
+				setStreamingChunk("");
+				setChunkCount(0);
+				const mediaRecorder = new MediaRecorder(stream);
+				mediaRecorderRef.current = mediaRecorder;
+				mediaRecorder.ondataavailable = (event) => {
+					if (event.data.size > 0) {
+						audioChunksRef.current.push(event.data);
+						if (streaming) pendingChunksRef.current.push(event.data);
+					}
+				};
+				mediaRecorder.start(100);
+				setIsRecording(true);
+				setError(null);
+				if (streaming && sttRef.current) {
+					let chunkIdx = 0;
+					let shouldContinue = true;
+					const processNextChunk = async () => {
+						if (!shouldContinue || !mountedRef.current) return;
+						if (pendingChunksRef.current.length > 0) {
+							pendingChunksRef.current = [];
+							try {
+								setIsTranscribing(true);
+								const chunkText = await transcribeChunk(chunkIdx);
+								if (chunkText && mountedRef.current) {
+									chunkIdx++;
+									setChunkCount(chunkIdx);
+									setTranscript((prev) => {
+										const newTranscript = prev + (prev ? " " : "") + chunkText;
+										fullTranscriptRef.current = newTranscript;
+										onTranscript?.(newTranscript);
+										return newTranscript;
+									});
+								}
+							} catch (e) {
+								console.error("[useVoiceInput] Chunk transcription error:", e);
+							} finally {
+								if (mountedRef.current) setIsTranscribing(false);
+							}
+						}
+						if (shouldContinue && mountedRef.current) streamingIntervalRef.current = setTimeout(processNextChunk, chunkDuration);
+					};
+					streamingIntervalRef.current = setTimeout(processNextChunk, chunkDuration);
+					streamingIntervalRef._stop = () => {
+						shouldContinue = false;
+					};
+				}
+			} catch (e) {
+				const errMsg = e.message || "Failed to start recording";
+				setError(errMsg);
+				onError?.(errMsg);
+			}
+		}, [
+			isRecording,
+			streaming,
+			shouldLoad,
+			model,
+			chunkDuration,
+			transcribeChunk,
+			onTranscript,
+			onError,
+			onProgress,
+			onReady
+		]),
+		stopRecording: useCallback(async () => {
+			if (streamingIntervalRef._stop) streamingIntervalRef._stop();
+			if (streamingIntervalRef.current) {
+				clearTimeout(streamingIntervalRef.current);
+				streamingIntervalRef.current = null;
+			}
+			return new Promise((resolve, reject) => {
+				if (!mediaRecorderRef.current || !isRecording) {
+					reject(/* @__PURE__ */ new Error("Not recording"));
+					return;
+				}
+				const mediaRecorder = mediaRecorderRef.current;
+				mediaRecorder.onstop = async () => {
+					if (streamRef.current) {
+						for (const track of streamRef.current.getTracks()) track.stop();
+						streamRef.current = null;
+					}
+					setIsRecording(false);
+					if (streaming) {
+						if (audioChunksRef.current.length > 0 && processedSamplesRef.current > 0) {
+							setIsTranscribing(true);
+							pendingChunksRef.current = [];
+							try {
+								const finalChunkText = await transcribeChunk(chunkCount);
+								if (finalChunkText && mountedRef.current) setTranscript((prev) => {
+									const newTranscript = prev + (prev ? " " : "") + finalChunkText;
+									fullTranscriptRef.current = newTranscript;
+									return newTranscript;
+								});
+							} finally {
+								if (mountedRef.current) setIsTranscribing(false);
+							}
+						}
+						const finalText = fullTranscriptRef.current;
+						onTranscript?.(finalText);
+						resolve(finalText);
+						return;
+					}
+					const audioBlob = new Blob(audioChunksRef.current, { type: "audio/webm" });
+					try {
+						if (!sttRef.current) {
+							if (!shouldLoad) setShouldLoad(true);
+							await new Promise((res, rej) => {
+								const checkReady = setInterval(() => {
+									if (sttRef.current) {
+										clearInterval(checkReady);
+										res();
+									}
+								}, 100);
+								setTimeout(() => {
+									clearInterval(checkReady);
+									rej(/* @__PURE__ */ new Error("Timeout waiting for STT model"));
+								}, 3e4);
+							});
+						}
+						resolve(await transcribe(await blobToFloat32(audioBlob)));
+					} catch (e) {
+						const errMsg = e.message || "Transcription failed";
+						setError(errMsg);
+						onError?.(errMsg);
+						reject(e);
+					}
+				};
+				mediaRecorder.stop();
+			});
+		}, [
+			isRecording,
+			streaming,
+			chunkCount,
+			shouldLoad,
+			blobToFloat32,
+			transcribe,
+			transcribeChunk,
+			onTranscript,
+			onError
+		]),
+		cancelRecording: useCallback(() => {
+			if (streamingIntervalRef._stop) streamingIntervalRef._stop();
+			if (streamingIntervalRef.current) {
+				clearTimeout(streamingIntervalRef.current);
+				streamingIntervalRef.current = null;
+			}
+			if (mediaRecorderRef.current && isRecording) mediaRecorderRef.current.stop();
+			if (streamRef.current) {
+				for (const track of streamRef.current.getTracks()) track.stop();
+				streamRef.current = null;
+			}
+			audioChunksRef.current = [];
+			pendingChunksRef.current = [];
+			processedSamplesRef.current = 0;
+			setIsRecording(false);
+		}, [isRecording]),
+		transcribe,
+		isRecording,
+		isTranscribing,
+		isLoading,
+		isReady,
+		transcript,
+		streamingChunk,
+		chunkCount,
+		loadingProgress,
+		error,
+		load
+	};
+}
+/**
+* React hook for voice conversation with STT + LLM + TTS
+*
+* Complete voice-to-voice conversation loop:
+* 1. User presses button to speak
+* 2. Speech is transcribed (Whisper)
+* 3. LLM generates response
+* 4. Response is spoken aloud (Kokoro or Supertonic TTS)
+*
+* @example
+* ```tsx
+* function VoiceChat() {
+*   const {
+*     messages,
+*     startListening,
+*     stopListening,
+*     isListening,
+*     isSpeaking,
+*     stage,
+*   } = useVoiceChat({
+*     system: "You are a helpful voice assistant.",
+*     voice: "af_bella",
+*     // Or use Supertonic for faster synthesis:
+*     // ttsModel: "supertonic-66m",
+*     // voice: "F1",
+*   });
+*
+*   return (
+*     <div>
+*       {messages.map(m => (
+*         <div key={m.id}>{m.role}: {m.content}</div>
+*       ))}
+*       <button
+*         onMouseDown={startListening}
+*         onMouseUp={stopListening}
+*       >
+*         {stage === "idle" ? "🎤 Hold to Speak" : stage}
+*       </button>
+*     </div>
+*   );
+* }
+* ```
+*/
+function useVoiceChat(options = {}) {
+	const React = globalThis.React;
+	if (!React) throw new Error("useVoiceChat requires React. Import React before using this hook.");
+	const { useState, useEffect, useRef, useCallback } = React;
+	const ttsModelId = options.ttsModel || "kokoro-82m";
+	const ttsConfig = TTS_MODELS[ttsModelId];
+	const { llmModel = "qwen3-0.6b", sttModel = "whisper-tiny.en", system = "You are a helpful voice assistant. Keep responses brief and conversational.", thinking = false, voice = ttsConfig.defaultVoice, speed = 1, autoLoad = false, onUserSpeak, onAssistantSpeak, onError } = options;
+	const [messages, setMessages] = useState([]);
+	const [stage, setStage] = useState("idle");
+	const [isLoading, setIsLoading] = useState(autoLoad);
+	const [loadingMessage, setLoadingMessage] = useState("");
+	const [isReady, setIsReady] = useState(false);
+	const [error, setError] = useState(null);
+	const [shouldLoad, setShouldLoad] = useState(autoLoad);
+	const llmWorkerRef = useRef(null);
+	const sttRef = useRef(null);
+	const ttsRef = useRef(null);
+	const mediaRecorderRef = useRef(null);
+	const audioChunksRef = useRef([]);
+	const streamRef = useRef(null);
+	const audioContextRef = useRef(null);
+	const sourceNodeRef = useRef(null);
+	const mountedRef = useRef(true);
+	const cancelledRef = useRef(false);
+	const isListening = stage === "listening";
+	const isProcessing = stage === "transcribing" || stage === "thinking";
+	const isSpeaking = stage === "speaking";
+	useEffect(() => {
+		if (!shouldLoad || isReady) return;
+		let cancelled = false;
+		const loadModels = async () => {
+			try {
+				setIsLoading(true);
+				setError(null);
+				setLoadingMessage("Loading speech recognition (Whisper)...");
+				const { WhisperSTT } = await import("../stt-KzSoNvwI.mjs");
+				if (cancelled || !mountedRef.current) return;
+				const stt = new WhisperSTT(sttModel);
+				await stt.load({ onProgress: (p) => {
+					if (!mountedRef.current) return;
+					setLoadingMessage(p.status || "Loading STT...");
+				} });
+				if (cancelled || !mountedRef.current) {
+					stt.dispose();
+					return;
+				}
+				sttRef.current = stt;
+				setLoadingMessage("Loading language model...");
+				const worker = await createGerbilWorker({
+					modelId: llmModel,
+					onProgress: (p) => {
+						if (!mountedRef.current) return;
+						setLoadingMessage(p.message || "Loading LLM...");
+					}
+				});
+				if (cancelled || !mountedRef.current) {
+					worker.terminate();
+					return;
+				}
+				llmWorkerRef.current = worker;
+				setLoadingMessage(`Loading text-to-speech (${ttsModelId === "supertonic-66m" ? "Supertonic" : "Kokoro"})...`);
+				const { createTTS } = await import("../tts-5yWeP_I0.mjs");
+				if (cancelled || !mountedRef.current) return;
+				const tts = createTTS(ttsModelId);
+				await tts.load({ onProgress: (p) => {
+					if (!mountedRef.current) return;
+					setLoadingMessage(p.status || "Loading TTS...");
+				} });
+				if (cancelled || !mountedRef.current) {
+					await tts.dispose();
+					return;
+				}
+				ttsRef.current = tts;
+				setIsReady(true);
+				setIsLoading(false);
+				setLoadingMessage("Ready!");
+			} catch (e) {
+				if (!mountedRef.current) return;
+				const errMsg = e.message || "Failed to load models";
+				setError(errMsg);
+				setIsLoading(false);
+				onError?.(errMsg);
+			}
+		};
+		loadModels();
+		return () => {
+			cancelled = true;
+		};
+	}, [
+		shouldLoad,
+		isReady,
+		llmModel,
+		sttModel,
+		ttsModelId,
+		onError
+	]);
+	useEffect(() => {
+		mountedRef.current = true;
+		return () => {
+			mountedRef.current = false;
+			llmWorkerRef.current?.terminate();
+			sttRef.current?.dispose();
+			ttsRef.current?.dispose();
+			if (streamRef.current) for (const track of streamRef.current.getTracks()) track.stop();
+			audioContextRef.current?.close();
+		};
+	}, []);
+	const load = useCallback(() => {
+		if (!shouldLoad && !isReady && !isLoading) setShouldLoad(true);
+	}, [
+		shouldLoad,
+		isReady,
+		isLoading
+	]);
+	const blobToFloat32 = useCallback(async (blob) => {
+		const audioContext = new AudioContext({ sampleRate: 16e3 });
+		const arrayBuffer = await blob.arrayBuffer();
+		const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
+		const channelData = audioBuffer.getChannelData(0);
+		if (audioBuffer.sampleRate !== 16e3) {
+			const ratio = 16e3 / audioBuffer.sampleRate;
+			const newLength = Math.round(channelData.length * ratio);
+			const resampled = new Float32Array(newLength);
+			for (let i = 0; i < newLength; i++) {
+				const srcIndex = i / ratio;
+				const floor = Math.floor(srcIndex);
+				const ceil = Math.min(floor + 1, channelData.length - 1);
+				const t = srcIndex - floor;
+				resampled[i] = channelData[floor] * (1 - t) + channelData[ceil] * t;
+			}
+			audioContext.close();
+			return resampled;
+		}
+		audioContext.close();
+		return new Float32Array(channelData);
+	}, []);
+	const playAudioBuffer = useCallback(async (audio, sampleRate) => {
+		return new Promise((resolve) => {
+			if (!audioContextRef.current) audioContextRef.current = new AudioContext();
+			const ctx = audioContextRef.current;
+			const buffer = ctx.createBuffer(1, audio.length, sampleRate);
+			const channelData = new Float32Array(audio);
+			buffer.copyToChannel(channelData, 0);
+			const source = ctx.createBufferSource();
+			source.buffer = buffer;
+			source.connect(ctx.destination);
+			source.onended = () => {
+				if (mountedRef.current) resolve();
+			};
+			source.start();
+			sourceNodeRef.current = source;
+		});
+	}, []);
+	return {
+		messages,
+		startListening: useCallback(async () => {
+			if (stage !== "idle") return;
+			if (!isReady && !isLoading) {
+				setShouldLoad(true);
+				return;
+			}
+			cancelledRef.current = false;
+			try {
+				const stream = await navigator.mediaDevices.getUserMedia({ audio: {
+					sampleRate: 16e3,
+					channelCount: 1,
+					echoCancellation: true
+				} });
+				streamRef.current = stream;
+				audioChunksRef.current = [];
+				const mediaRecorder = new MediaRecorder(stream);
+				mediaRecorderRef.current = mediaRecorder;
+				mediaRecorder.ondataavailable = (event) => {
+					if (event.data.size > 0) audioChunksRef.current.push(event.data);
+				};
+				mediaRecorder.start(100);
+				setStage("listening");
+				setError(null);
+			} catch (e) {
+				const errMsg = e.message || "Failed to access microphone";
+				setError(errMsg);
+				onError?.(errMsg);
+			}
+		}, [
+			stage,
+			isReady,
+			isLoading,
+			onError
+		]),
+		stopListening: useCallback(async () => {
+			if (stage !== "listening") return;
+			const mediaRecorder = mediaRecorderRef.current;
+			if (!mediaRecorder) return;
+			return new Promise((resolve) => {
+				mediaRecorder.onstop = async () => {
+					if (streamRef.current) {
+						for (const track of streamRef.current.getTracks()) track.stop();
+						streamRef.current = null;
+					}
+					if (cancelledRef.current) {
+						setStage("idle");
+						resolve();
+						return;
+					}
+					const audioBlob = new Blob(audioChunksRef.current, { type: "audio/webm" });
+					try {
+						setStage("transcribing");
+						const audioData = await blobToFloat32(audioBlob);
+						let userText = (await sttRef.current.transcribe(audioData)).text.trim();
+						if (userText === "[BLANK_AUDIO]" || userText === "(blank audio)" || userText === "[BLANK AUDIO]") userText = "";
+						if (cancelledRef.current || !userText) {
+							setStage("idle");
+							resolve();
+							return;
+						}
+						const userMsgId = `user-${Date.now()}`;
+						setMessages((m) => [...m, {
+							id: userMsgId,
+							role: "user",
+							content: userText
+						}]);
+						onUserSpeak?.(userText);
+						setStage("thinking");
+						const history = messages.map((m) => ({
+							role: m.role,
+							content: m.content
+						}));
+						history.push({
+							role: "user",
+							content: userText
+						});
+						let responseText = "";
+						let thinkingText = "";
+						await llmWorkerRef.current.generate(userText, {
+							system,
+							thinking,
+							history,
+							onToken: (token) => {
+								if (cancelledRef.current) return;
+								if (token.state === "thinking") thinkingText += token.text;
+								else responseText += token.text;
+							}
+						});
+						if (cancelledRef.current) {
+							setStage("idle");
+							resolve();
+							return;
+						}
+						const assistantMsgId = `assistant-${Date.now()}`;
+						setMessages((m) => [...m, {
+							id: assistantMsgId,
+							role: "assistant",
+							content: responseText,
+							thinking: thinkingText || void 0
+						}]);
+						onAssistantSpeak?.(responseText);
+						if (responseText.trim()) {
+							setStage("speaking");
+							const ttsResult = await ttsRef.current.speak(responseText, {
+								voice,
+								speed
+							});
+							if (!cancelledRef.current) await playAudioBuffer(ttsResult.audio, ttsResult.sampleRate);
+						}
+						setStage("idle");
+						resolve();
+					} catch (e) {
+						if (!mountedRef.current) return;
+						const errMsg = e.message || "Processing failed";
+						setError(errMsg);
+						setStage("idle");
+						onError?.(errMsg);
+						resolve();
+					}
+				};
+				mediaRecorder.stop();
+			});
+		}, [
+			stage,
+			messages,
+			system,
+			thinking,
+			voice,
+			speed,
+			blobToFloat32,
+			playAudioBuffer,
+			onUserSpeak,
+			onAssistantSpeak,
+			onError
+		]),
+		cancel: useCallback(() => {
+			cancelledRef.current = true;
+			if (mediaRecorderRef.current && stage === "listening") mediaRecorderRef.current.stop();
+			if (streamRef.current) {
+				for (const track of streamRef.current.getTracks()) track.stop();
+				streamRef.current = null;
+			}
+			if (sourceNodeRef.current) try {
+				sourceNodeRef.current.stop();
+			} catch {}
+			audioChunksRef.current = [];
+			setStage("idle");
+		}, [stage]),
+		clear: useCallback(() => {
+			setMessages([]);
+		}, []),
+		isListening,
+		isProcessing,
+		isSpeaking,
+		stage,
+		isReady,
+		isLoading,
+		loadingMessage,
+		error,
+		load
+	};
+}
 /**
 * Check if WebGPU is supported
 */
@@ -747,9 +2371,11 @@ async function getWebGPUInfo() {
 var browser_default = {
 	isWebGPUSupported,
 	getWebGPUInfo,
-	createGerbilWorker
+	createGerbilWorker,
+	playAudio,
+	createAudioPlayer
 };
 
 //#endregion
-export { BUILTIN_MODELS, createGerbilWorker, browser_default as default, getWebGPUInfo, isWebGPUSupported, useChat, useCompletion };
+export { BUILTIN_MODELS, createAudioPlayer, createGerbilWorker, browser_default as default, getWebGPUInfo, isWebGPUSupported, playAudio, useChat, useCompletion, useSpeech, useVoiceChat, useVoiceInput };
 //# sourceMappingURL=index.mjs.map