@tryhamster/gerbil 1.0.0-rc.9 → 1.0.1

package/dist/browser/index.js

@@ -1,1586 +1,159 @@
 //#region src/core/models.ts
 const BUILTIN_MODELS = {
-	"qwen3-0.6b": {
-		id: "qwen3-0.6b",
-		repo: "onnx-community/Qwen3-0.6B-ONNX",
-		description: "Qwen3 0.6B - Best balance of speed and quality, supports thinking",
-		size: "~400MB",
-		contextLength: 32768,
+	"qwen3.5-0.8b": {
+		id: "qwen3.5-0.8b",
+		repo: "Qwen/Qwen3.5-0.8B",
+		description: "Qwen3.5 0.8B - Fast, multimodal (vision), 262k context, supports thinking (default)",
+		size: "~1.6GB",
+		contextLength: 262144,
 		supportsThinking: true,
 		supportsJson: true,
+		supportsVision: true,
 		family: "qwen"
 	},
-	"qwen2.5-0.5b": {
-		id: "qwen2.5-0.5b",
-		repo: "onnx-community/Qwen2.5-0.5B-Instruct",
-		description: "Qwen2.5 0.5B - Fast and capable",
-		size: "~350MB",
-		contextLength: 32768,
-		supportsThinking: false,
-		supportsJson: true,
-		family: "qwen"
-	},
-	"qwen2.5-coder-0.5b": {
-		id: "qwen2.5-coder-0.5b",
-		repo: "onnx-community/Qwen2.5-Coder-0.5B-Instruct",
-		description: "Qwen2.5 Coder 0.5B - Optimized for code",
-		size: "~400MB",
-		contextLength: 32768,
-		supportsThinking: false,
-		supportsJson: true,
-		family: "qwen"
-	},
-	"smollm2-360m": {
-		id: "smollm2-360m",
-		repo: "HuggingFaceTB/SmolLM2-360M-Instruct",
-		description: "SmolLM2 360M - Fast, good for simple tasks",
-		size: "~250MB",
-		contextLength: 8192,
-		supportsThinking: false,
-		supportsJson: false,
-		family: "smollm"
-	},
-	"smollm2-135m": {
-		id: "smollm2-135m",
-		repo: "HuggingFaceTB/SmolLM2-135M-Instruct",
-		description: "SmolLM2 135M - Fastest, basic generation",
-		size: "~100MB",
-		contextLength: 8192,
-		supportsThinking: false,
-		supportsJson: false,
-		family: "smollm"
-	},
-	"phi-3-mini": {
-		id: "phi-3-mini",
-		repo: "microsoft/Phi-3-mini-4k-instruct-onnx",
-		description: "Phi-3 Mini - High quality, larger model",
-		size: "~2.1GB",
-		contextLength: 4096,
-		supportsThinking: false,
-		supportsJson: true,
-		family: "phi"
-	},
-	"ministral-3b": {
-		id: "ministral-3b",
-		repo: "mistralai/Ministral-3-3B-Instruct-2512-ONNX",
-		description: "Ministral 3 3B - Vision + Reasoning, 256k context",
-		size: "~2.5GB",
+	"qwen3.5-2b": {
+		id: "qwen3.5-2b",
+		repo: "Qwen/Qwen3.5-2B",
+		description: "Qwen3.5 2B - Higher quality, multimodal (vision), 262k context, supports thinking",
+		size: "~4GB",
 		contextLength: 262144,
 		supportsThinking: true,
 		supportsJson: true,
 		supportsVision: true,
-		visionEncoderSize: "0.4B",
-		family: "mistral"
+		family: "qwen"
+	},
+	"lfm2.5-1.2b-thinking": {
+		id: "lfm2.5-1.2b-thinking",
+		repo: "LiquidAI/LFM2.5-1.2B-Thinking",
+		description: "LFM2.5 1.2B Thinking - Efficient reasoning model, 128k context",
+		size: "~2.4GB",
+		contextLength: 128e3,
+		supportsThinking: true,
+		supportsJson: false,
+		family: "other"
 	}
 };
-/**
-* Parse model identifier and resolve to source
-*
-* Supported formats:
-* - "qwen3-0.6b" (built-in)
-* - "hf:org/model" (HuggingFace shorthand)
-* - "https://huggingface.co/org/model" (full URL)
-* - "file:./path/to/model" (local path)
-*/
-function resolveModel(modelId) {
-	if (BUILTIN_MODELS[modelId]) return {
-		type: "builtin",
-		path: BUILTIN_MODELS[modelId].repo
-	};
-	if (modelId.startsWith("hf:")) return {
-		type: "huggingface",
-		path: modelId.slice(3)
-	};
-	if (modelId.startsWith("https://huggingface.co/")) return {
-		type: "huggingface",
-		path: modelId.replace("https://huggingface.co/", "")
-	};
-	if (modelId.startsWith("file:")) return {
-		type: "local",
-		path: modelId.slice(5)
-	};
-	if (modelId.includes("/")) return {
-		type: "huggingface",
-		path: modelId
-	};
-	return {
-		type: "huggingface",
-		path: modelId
-	};
-}
 
 //#endregion
-//#region src/browser/index.ts
+//#region src/browser/pwa.ts
 /**
-* Gerbil Browser Support
-*
-* Run LLMs directly in the browser with WebGPU acceleration.
-*
-* @example useChat (React)
-* ```tsx
-* import { useChat } from "@tryhamster/gerbil/browser";
-*
-* function Chat() {
-*   const { messages, input, setInput, handleSubmit, isLoading } = useChat();
-*
-*   if (isLoading) return <div>Loading model...</div>;
+* Mobile / PWA storage helpers.
 *
-*   return (
-*     <form onSubmit={handleSubmit}>
-*       {messages.map(m => <div key={m.id}>{m.role}: {m.content}</div>)}
-*       <input value={input} onChange={e => setInput(e.target.value)} />
-*     </form>
-*   );
-* }
-* ```
-*
-* @example useCompletion (React)
-* ```tsx
-* import { useCompletion } from "@tryhamster/gerbil/browser";
+* On-device models are large (a 4-bit 0.8B is ~400 MB; vision/larger models are
+* GBs). Mobile browsers — iOS Safari especially — wall a web origin off from the
+* real disk with TWO independent ceilings:
 *
-* function App() {
-*   const { complete, completion, isLoading } = useCompletion();
-*   if (isLoading) return <div>Loading...</div>;
-*   return <button onClick={() => complete("Write a haiku")}>{completion}</button>;
-* }
-* ```
+*   1. **Storage quota** (disk for the model cache). An *uninstalled* Safari tab
+*      gets only ~1 GB, best-effort and evictable, regardless of how much free
+*      disk the device has. Exceed it and every cache write fails → the model
+*      re-downloads on every visit.
+*   2. **Tab memory** (RAM during load/inference) — a separate, smaller ceiling.
 *
-* @example Low-level API
-* ```ts
-* import { createGerbilWorker } from "@tryhamster/gerbil/browser";
+* The unlock for the storage ceiling is **persistent storage**, which iOS Safari
+* grants when the site is **installed to the Home Screen** (a PWA). Installed, the
+* quota jumps to a large fraction of actual disk and is never evicted — so models
+* cache once and stay. These helpers let an app surface that to its users and
+* request it, so on-device AI is actually practical on mobile.
 *
-* const gerbil = await createGerbilWorker({
-*   modelId: "qwen3-0.6b",
-*   onToken: (token) => console.log(token.text),
-* });
-* await gerbil.generate("Hello!");
-* gerbil.terminate();
-* ```
+* All functions are SSR/Node-safe (guarded; return conservative defaults).
 */
-/**
-* Create a Gerbil worker for streaming WebGPU inference
-*
-* Uses a Web Worker to keep the UI responsive during model loading
-* and text generation, with real-time token streaming.
-*/
-async function createGerbilWorker(options = {}) {
-	const { modelId = "qwen3-0.6b", onProgress, onToken, onComplete, onError } = options;
-	const source = resolveModel(modelId);
-	return new Promise((resolve, reject) => {
-		const blob = new Blob([`
-      import {
-        AutoTokenizer,
-        AutoModelForCausalLM,
-        AutoProcessor,
-        AutoModelForImageTextToText,
-        RawImage,
-        TextStreamer,
-        InterruptableStoppingCriteria,
-        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.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 
-            };
-          }
-        }
-      }
-
-      const stoppingCriteria = new InterruptableStoppingCriteria();
-      let pastKeyValuesCache = null;
-
-      async function load(data) {
-        const { modelId, options = {} } = data;
-        self.postMessage({ status: "loading", message: "Loading model..." });
-
-        const downloadState = {
-          downloading: new Set(),
-          completed: new Set(),
-          isDownloading: false,
-        };
-
-        try {
-          const result = await ModelPipeline.getInstance(
-            modelId,
-            options,
-            (progress) => {
-              if (progress.status === "progress" && progress.file) {
-                const pct = Math.round(progress.progress || 0);
-                if (pct < 100) {
-                  downloadState.downloading.add(progress.file);
-                  downloadState.isDownloading = true;
-                } else if (pct === 100) {
-                  downloadState.downloading.delete(progress.file);
-                  downloadState.completed.add(progress.file);
-                }
-                if (downloadState.isDownloading) {
-                  self.postMessage({
-                    status: "downloading",
-                    file: progress.file,
-                    progress: pct,
-                    downloadCount: downloadState.downloading.size,
-                    totalFiles: downloadState.completed.size + downloadState.downloading.size,
-                  });
-                }
-              }
-            }
-          );
-
-          self.postMessage({ status: "loading", message: "Compiling shaders..." });
-          
-          // 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", isVision: result.isVision });
-        } catch (error) {
-          self.postMessage({ status: "error", error: error.message || String(error) });
-        }
-      }
-
-      async function generate(data) {
-        const { messages, images = [], options = {} } = data;
-        const { maxTokens = 256, temperature = 0.7, topP = 0.9, topK = 20, thinking = false } = options;
-
-        try {
-          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) {
-          case "load": await load(data); break;
-          case "generate": stoppingCriteria.reset(); await generate(data); break;
-          case "interrupt": stoppingCriteria.interrupt(); break;
-          case "reset": pastKeyValuesCache = null; stoppingCriteria.reset(); break;
-        }
-      });
-
-      self.postMessage({ status: "init" });
-    `], { type: "application/javascript" });
-		const workerUrl = URL.createObjectURL(blob);
-		const worker = new Worker(workerUrl, { type: "module" });
-		let isReady = false;
-		let currentResolve = null;
-		let currentReject = null;
-		let _generatedText = "";
-		worker.onmessage = (e) => {
-			const msg = e.data;
-			switch (msg.status) {
-				case "init":
-					worker.postMessage({
-						type: "load",
-						modelId: source.path
-					});
-					break;
-				case "loading":
-				case "downloading":
-					onProgress?.(msg);
-					break;
-				case "ready":
-					isReady = true;
-					onProgress?.(msg);
-					resolve(gerbilWorker);
-					break;
-				case "start":
-					_generatedText = "";
-					break;
-				case "token":
-					_generatedText += msg.text;
-					onToken?.(msg);
-					break;
-				case "complete":
-					onComplete?.(msg);
-					currentResolve?.(msg.text);
-					currentResolve = null;
-					currentReject = null;
-					break;
-				case "error":
-					onError?.(msg.error);
-					onProgress?.({
-						status: "error",
-						error: msg.error
-					});
-					if (currentReject) {
-						currentReject(new Error(msg.error));
-						currentResolve = null;
-						currentReject = null;
-					} else reject(new Error(msg.error));
-					break;
-			}
-		};
-		worker.onerror = (e) => {
-			const error = e.message || "Worker error";
-			onError?.(error);
-			reject(new Error(error));
-		};
-		const gerbilWorker = {
-			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" });
-			},
-			reset: () => {
-				worker.postMessage({ type: "reset" });
-			},
-			terminate: () => {
-				worker.terminate();
-				URL.revokeObjectURL(workerUrl);
-			},
-			isReady: () => isReady
-		};
-	});
+/** True when the page is running as an installed/standalone PWA (Home Screen). */
+function isStandalone() {
+	if (typeof window === "undefined") return false;
+	const iosStandalone = navigator.standalone === true;
+	const displayStandalone = typeof window.matchMedia === "function" && window.matchMedia("(display-mode: standalone)").matches;
+	return iosStandalone || displayStandalone;
 }
-/**
-* React hook for chat with local LLM
-*
-* @example
-* ```tsx
-* import { useChat } from "@tryhamster/gerbil/browser";
-*
-* function Chat() {
-*   const { messages, input, setInput, handleSubmit, isLoading, isGenerating } = useChat();
-*
-*   if (isLoading) return <div>Loading model...</div>;
-*
-*   return (
-*     <div>
-*       {messages.map(m => (
-*         <div key={m.id}>{m.role}: {m.content}</div>
-*       ))}
-*       <form onSubmit={handleSubmit}>
-*         <input value={input} onChange={e => setInput(e.target.value)} />
-*         <button disabled={isGenerating}>Send</button>
-*       </form>
-*     </div>
-*   );
-* }
-* ```
-*/
-function useChat(options = {}) {
-	const React = globalThis.React;
-	if (!React) throw new Error("useChat requires React. Import React before using this hook.");
-	const { useState, useEffect, useRef, useCallback } = React;
-	const { model = "qwen3-0.6b", system = "You are a helpful assistant.", thinking: enableThinking = false, maxTokens = 512, temperature = .7, initialMessages = [], autoLoad = false, onReady, onError } = options;
-	const [messages, setMessages] = useState(initialMessages);
-	const [input, setInput] = useState("");
-	const [isLoading, setIsLoading] = useState(autoLoad);
-	const [loadingProgress, setLoadingProgress] = useState(null);
-	const [isGenerating, setIsGenerating] = useState(false);
-	const [thinking, setThinking] = useState("");
-	const [currentResponse, setCurrentResponse] = useState("");
-	const [tps, setTps] = useState(0);
-	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);
-	const load = useCallback(() => {
-		if (workerRef.current || isLoading) return;
-		setIsLoading(true);
-		setShouldLoad(true);
-	}, [isLoading]);
-	useEffect(() => {
-		if (!shouldLoad) return;
-		if (!isWebGPUSupported()) {
-			setError("WebGPU not supported. Use Chrome/Edge 113+.");
-			setIsLoading(false);
-			onError?.("WebGPU not supported");
-			return;
-		}
-		mountedRef.current = true;
-		createGerbilWorker({
-			modelId: model,
-			onProgress: (p) => {
-				if (!mountedRef.current) return;
-				setLoadingProgress(p);
-				if (p.status === "ready") {
-					setIsLoading(false);
-					setIsReady(true);
-					onReady?.();
-				}
-			},
-			onToken: (token) => {
-				if (!mountedRef.current) return;
-				setTps(token.tps);
-				if (token.state === "thinking") setThinking((t) => t + token.text);
-				else setCurrentResponse((r) => r + token.text);
-			},
-			onComplete: () => {
-				if (!mountedRef.current) return;
-				setIsGenerating(false);
-			},
-			onError: (err) => {
-				if (!mountedRef.current) return;
-				setError(err);
-				setIsGenerating(false);
-				onError?.(err);
-			}
-		}).then((worker) => {
-			if (mountedRef.current) workerRef.current = worker;
-			else worker.terminate();
-		}).catch((err) => {
-			if (mountedRef.current) {
-				setError(err.message);
-				setIsLoading(false);
-				onError?.(err.message);
-			}
-		});
-		return () => {
-			mountedRef.current = false;
-			workerRef.current?.terminate();
-		};
-	}, [model, shouldLoad]);
-	useEffect(() => {
-		if (!isGenerating && currentResponse) {
-			setMessages((msgs) => {
-				if (msgs.at(-1)?.role === "assistant") return msgs.map((m, i) => i === msgs.length - 1 ? {
-					...m,
-					content: currentResponse,
-					thinking: thinking || void 0
-				} : m);
-				return msgs;
-			});
-			setCurrentResponse("");
-			setThinking("");
-		}
-	}, [
-		isGenerating,
-		currentResponse,
-		thinking
-	]);
-	const pendingMessageRef = useRef(null);
-	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}`,
-			role: "user",
-			content: text.trim(),
-			images: images.length > 0 ? images : void 0
-		};
-		messageIdRef.current += 1;
-		const assistantMessage = {
-			id: `msg-${messageIdRef.current}`,
-			role: "assistant",
-			content: ""
-		};
-		setMessages((msgs) => [
-			...msgs,
-			userMessage,
-			assistantMessage
-		]);
-		setCurrentResponse("");
-		setThinking("");
-		if (!workerRef.current) {
-			pendingMessageRef.current = text.trim();
-			pendingImagesRef.current = images;
-			load();
-			return;
-		}
-		setIsGenerating(true);
-		workerRef.current.generate(text.trim(), {
-			system,
-			thinking: enableThinking,
-			maxTokens: images.length > 0 ? Math.max(maxTokens, 2048) : maxTokens,
-			temperature,
-			images: images.length > 0 ? images : void 0
-		});
-	}, [
-		isGenerating,
-		system,
-		enableThinking,
-		maxTokens,
-		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: pendingImages.length > 0 ? Math.max(maxTokens, 2048) : maxTokens,
-				temperature,
-				images: pendingImages.length > 0 ? pendingImages : void 0
-			});
-		}
-	}, [
-		isReady,
-		system,
-		enableThinking,
-		maxTokens,
-		temperature
-	]);
-	const stop = useCallback(() => {
-		workerRef.current?.interrupt();
-		setIsGenerating(false);
-	}, []);
-	const clear = useCallback(() => {
-		workerRef.current?.reset();
-		setMessages([]);
-		setCurrentResponse("");
-		setThinking("");
-		setAttachedImages([]);
-	}, []);
+/** True when running on iOS/iPadOS (where install is the quota unlock and the
+* install flow is manual: Share → Add to Home Screen). iPadOS masquerades as
+* macOS, so we also treat touch-capable WebKit-on-Mac as iOS. */
+function isIOS() {
+	if (typeof navigator === "undefined") return false;
+	const ua = navigator.userAgent || "";
+	if (/iPhone|iPad|iPod/.test(ua)) return true;
+	return /Macintosh/.test(ua) && /AppleWebKit/.test(ua) && !/Chrome/.test(ua) && (navigator.maxTouchPoints ?? 0) > 1;
+}
+/** Snapshot of the origin's storage situation — quota, usage, persistence, and
+* whether the app is installed. Use it to decide whether to recommend install
+* before downloading a large model. */
+async function getStorageStatus() {
+	const installed = isStandalone();
+	const ios = isIOS();
+	let quotaMB = 0;
+	let usageMB = 0;
+	let persisted = false;
+	try {
+		const est = await navigator.storage?.estimate?.();
+		quotaMB = Math.round((est?.quota || 0) / 1e6);
+		usageMB = Math.round((est?.usage || 0) / 1e6);
+	} catch {}
+	try {
+		persisted = await navigator.storage?.persisted?.() ?? false;
+	} catch {}
 	return {
-		messages: messages.map((m, i) => {
-			if (i === messages.length - 1 && m.role === "assistant" && isGenerating) return {
-				...m,
-				content: currentResponse,
-				thinking: thinking || void 0
-			};
-			return m;
-		}),
-		input,
-		setInput,
-		handleSubmit,
-		isLoading,
-		loadingProgress,
-		isGenerating,
-		thinking,
-		stop,
-		clear,
-		tps,
-		isReady,
-		error,
-		load,
-		attachedImages,
-		attachImage,
-		removeImage,
-		clearImages,
-		sendWithImages
+		quotaMB,
+		usageMB,
+		availableMB: Math.max(0, quotaMB - usageMB),
+		persisted,
+		installed,
+		ios
 	};
 }
 /**
-* React hook for text completion with local LLM
-*
-* @example
-* ```tsx
-* import { useCompletion } from "@tryhamster/gerbil/browser";
-*
-* function App() {
-*   const { complete, completion, isLoading, isGenerating } = useCompletion();
-*
-*   if (isLoading) return <div>Loading...</div>;
-*
-*   return (
-*     <div>
-*       <button onClick={() => complete("Write a haiku")}>Generate</button>
-*       <p>{completion}</p>
-*     </div>
-*   );
-* }
-* ```
+* Request persistent storage (exempt from eviction). Returns whether the origin
+* is persistent afterwards. Browsers grant this based on engagement/installation;
+* on iOS Safari it is effectively granted only to an installed (Home Screen) PWA,
+* so call this AND guide users to install when it returns false on iOS.
 */
-function useCompletion(options = {}) {
-	const React = globalThis.React;
-	if (!React) throw new Error("useCompletion requires React. Import React before using this hook.");
-	const { useState, useEffect, useRef, useCallback } = React;
-	const { model = "qwen3-0.6b", system = "You are a helpful assistant.", thinking: enableThinking = false, maxTokens = 512, temperature = .7, autoLoad = false, onReady, onError } = options;
-	const [completion, setCompletion] = useState("");
-	const [thinking, setThinking] = useState("");
-	const [isLoading, setIsLoading] = useState(autoLoad);
-	const [loadingProgress, setLoadingProgress] = useState(null);
-	const [isGenerating, setIsGenerating] = useState(false);
-	const [tps, setTps] = useState(0);
-	const [error, setError] = useState(null);
-	const [isReady, setIsReady] = useState(false);
-	const [shouldLoad, setShouldLoad] = useState(autoLoad);
-	const workerRef = useRef(null);
-	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;
-		setIsLoading(true);
-		setShouldLoad(true);
-	}, [isLoading]);
-	useEffect(() => {
-		if (!shouldLoad) return;
-		if (!isWebGPUSupported()) {
-			setError("WebGPU not supported. Use Chrome/Edge 113+.");
-			setIsLoading(false);
-			onError?.("WebGPU not supported");
-			return;
-		}
-		mountedRef.current = true;
-		createGerbilWorker({
-			modelId: model,
-			onProgress: (p) => {
-				if (!mountedRef.current) return;
-				setLoadingProgress(p);
-				if (p.status === "ready") {
-					setIsLoading(false);
-					setIsReady(true);
-					onReady?.();
-				}
-			},
-			onToken: (token) => {
-				if (!mountedRef.current) return;
-				setTps(token.tps);
-				if (token.state === "thinking") setThinking((t) => t + token.text);
-				else setCompletion((c) => c + token.text);
-			},
-			onComplete: (result) => {
-				if (!mountedRef.current) return;
-				setIsGenerating(false);
-				resolveRef.current?.(result.text);
-				resolveRef.current = null;
-			},
-			onError: (err) => {
-				if (!mountedRef.current) return;
-				setError(err);
-				setIsGenerating(false);
-				onError?.(err);
-			}
-		}).then((worker) => {
-			if (mountedRef.current) workerRef.current = worker;
-			else worker.terminate();
-		}).catch((err) => {
-			if (mountedRef.current) {
-				setError(err.message);
-				setIsLoading(false);
-				onError?.(err.message);
-			}
-		});
-		return () => {
-			mountedRef.current = false;
-			workerRef.current?.terminate();
-		};
-	}, [model, shouldLoad]);
-	const complete = useCallback((prompt, completeOptions) => {
-		return new Promise((resolve, reject) => {
-			setCompletion("");
-			setThinking("");
-			resolveRef.current = resolve;
-			rejectRef.current = reject;
-			if (!workerRef.current) {
-				pendingPromptRef.current = prompt;
-				pendingImagesRef.current = completeOptions?.images;
-				load();
-				return;
-			}
-			setIsGenerating(true);
-			workerRef.current.generate(prompt, {
-				system,
-				thinking: enableThinking,
-				maxTokens,
-				temperature,
-				images: completeOptions?.images
-			});
-		});
-	}, [
-		system,
-		enableThinking,
-		maxTokens,
-		temperature,
-		load
-	]);
-	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,
-				images: pendingImages
-			});
-		}
-	}, [
-		isReady,
-		system,
-		enableThinking,
-		maxTokens,
-		temperature
-	]);
+async function requestPersistentStorage() {
+	try {
+		if (await navigator.storage?.persisted?.()) return true;
+		return await navigator.storage?.persist?.() ?? false;
+	} catch {
+		return false;
+	}
+}
+/**
+* Estimate whether a model of `sizeMB` will cache in the current quota, and
+* whether you should recommend installing to the Home Screen first. Pair with a
+* one-time "Install for offline use" prompt before a large download on mobile.
+*/
+async function canCacheModel(sizeMB) {
+	const s = await getStorageStatus();
+	const fits = s.availableMB >= sizeMB * 1.1;
+	const recommendInstall = (!fits || s.ios && !s.installed) && !s.persisted;
 	return {
-		completion,
-		thinking,
-		complete,
-		isLoading,
-		loadingProgress,
-		isGenerating,
-		stop: useCallback(() => {
-			workerRef.current?.interrupt();
-			setIsGenerating(false);
-		}, []),
-		tps,
-		isReady,
-		error,
-		load
+		fits,
+		availableMB: s.availableMB,
+		recommendInstall
 	};
 }
-/** 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>
-*   );
-* }
-* ```
+* Platform-appropriate install guidance. iOS Safari has NO programmatic install
+* prompt — installation is manual (Share → Add to Home Screen), so apps should
+* show these instructions. Other platforms (Android/Chrome) fire
+* `beforeinstallprompt`, which apps can capture for a one-tap button.
 */
-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("../transformers.web-u34VxRFM.js");
-					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-CMOGDSgT.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 {}
-		};
-	}, []);
+function getInstallGuidance() {
+	if (isStandalone()) return {
+		installed: true,
+		manual: false,
+		steps: "Already installed."
+	};
+	if (isIOS()) return {
+		installed: false,
+		manual: true,
+		steps: "Tap the Share button, then 'Add to Home Screen'. Installing unlocks durable storage so models download once instead of every visit."
+	};
 	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
+		installed: false,
+		manual: false,
+		steps: "Use your browser's Install option (or the install icon in the address bar) to add this app for offline use and durable model storage."
 	};
 }
+
+//#endregion
+//#region src/browser/audio.ts
 /**
 * Play audio from Float32Array using Web Audio API
 *
@@ -1673,819 +246,504 @@ function createAudioPlayer(sampleRate = 24e3) {
 		isPlaying: () => isActive
 	};
 }
+
+//#endregion
+//#region src/browser/device-guards.ts
+/** Recommended safe model ids per modality (used as fallbacks on mobile). */
+const SAFE_MOBILE_CHAT = "mlx-community/Qwen3.5-0.8B-4bit";
 /**
-* 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>
-*   );
-* }
-* ```
+* Approximate on-device (INT4) memory footprint in MB for the models the native
+* engine actually ships. Used for memory-aware selection and messaging.
 */
-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-Bu-E23Sc.js");
-				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);
-			}
+const MODEL_SIZES = {
+	"qwen3.5-0.8b": 650,
+	"qwen3.5-2b": 1700,
+	"gemma-4-e2b": 3600,
+	"lfm2.5-350m": 300,
+	"kokoro-82m": 350,
+	"supertonic-66m": 300,
+	"whisper-tiny": 150,
+	"whisper-tiny.en": 150,
+	"whisper-small": 500,
+	"all-minilm-l6-v2": 100
+};
+/**
+* Normalize a repo/model id to a lowercase token stream for substring matching
+* (strips org prefixes' punctuation while preserving the model name tokens).
+*/
+function normalizeId(modelId) {
+	return modelId.toLowerCase().replace(/[^a-z0-9]/g, "-");
+}
+/**
+* iOS (WKWebView) model classification keyed off the REAL native-engine ids.
+*
+* - blocked: too large for the WKWebView memory ceiling on iPhone — will crash.
+*   gemma-4-e2b (~3.6GB) plus any vision checkpoint (the vision encoder pushes
+*   the working set well past what an iPhone can hold).
+* - risky: Qwen3.5-2B (~1.7GB) OOM-crashes iPhone WKWebView in practice — now
+*   treated as unsafe to auto-load (flagged `risky` so a UI can offer to force it).
+* - everything else (Qwen3.5-0.8B ~0.65GB, LFM2.5-350M) is allowed everywhere.
+*/
+const IOS_MODEL_LIMITS = {
+	blocked: ["gemma-4-e2b", "gemma-4-e4b"],
+	visionMarkers: [
+		"vision",
+		"-vl-",
+		"-vl",
+		"vlm",
+		"image-text",
+		"-it-vision"
+	],
+	risky: ["qwen3.5-2b", "qwen3-5-2b"],
+	maxBudgetMB: 1800
+};
+/**
+* Check if a model is safe to load on the current device.
+* Returns guidance specific to iOS memory constraints. Matches on the real
+* native-engine repo ids (MLX 4-bit / upstream Qwen / Liquid).
+*/
+function isModelSafeForDevice(modelId) {
+	const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+	const isIPhone = /iPhone|iPod/.test(ua);
+	const isIPad = /iPad/.test(ua);
+	const isIOSChrome = (isIPhone || isIPad) && /CriOS/.test(ua);
+	const normalizedId = normalizeId(modelId);
+	const isVision = IOS_MODEL_LIMITS.visionMarkers.some((m) => normalizedId.includes(normalizeId(m)));
+	const isBlocked = IOS_MODEL_LIMITS.blocked.some((m) => normalizedId.includes(normalizeId(m))) || isVision;
+	const isRisky = IOS_MODEL_LIMITS.risky.some((m) => normalizedId.includes(normalizeId(m)));
+	if (isIPhone) {
+		if (isBlocked) return {
+			safe: false,
+			risky: false,
+			reason: `Model ${modelId} will crash on iPhone${isIOSChrome ? " (iOS Chrome uses WKWebView, same limits as Safari)" : ""}. ${isVision ? "Vision checkpoints need a separate image encoder in memory" : "It is too large (~3.6GB)"}, which exceeds the WKWebView memory ceiling.`,
+			recommendation: `Use ${SAFE_MOBILE_CHAT} (Qwen3.5-0.8B) on iPhone, or run larger models on desktop.`,
+			maxSafeModel: SAFE_MOBILE_CHAT
+		};
+		if (isRisky) return {
+			safe: false,
+			risky: true,
+			reason: `Model ${modelId} (~1.7GB) exceeds the iPhone WKWebView memory budget and is likely to crash.`,
+			recommendation: `Use ${SAFE_MOBILE_CHAT} (Qwen3.5-0.8B) on iPhone; run Qwen3.5-2B on iPad or desktop.`,
+			maxSafeModel: SAFE_MOBILE_CHAT
 		};
-		loadModel();
-		return () => {
-			cancelled = true;
+		return {
+			safe: true,
+			risky: false,
+			reason: "Model is within iPhone memory limits."
 		};
-	}, [
-		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();
+	}
+	if (isIPad) {
+		if (isBlocked) return {
+			safe: false,
+			risky: false,
+			reason: `Model ${modelId} may crash on iPad. ${isVision ? "Vision checkpoints need a separate image encoder in memory" : "It is too large (~3.6GB)"}, which can exceed the WKWebView memory ceiling.`,
+			recommendation: `Use ${SAFE_MOBILE_CHAT} (Qwen3.5-0.8B) or Qwen3.5-2B on iPad.`,
+			maxSafeModel: "mlx-community/Qwen3.5-2B-4bit"
 		};
-	}, []);
-	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 {
+			safe: true,
+			risky: false,
+			reason: "Model is within iPad memory limits."
+		};
+	}
+	if (/Android/.test(ua) && isBlocked) return {
+		safe: false,
+		risky: false,
+		reason: `Model ${modelId} is very large and may crash on Android devices.`,
+		recommendation: `Use ${SAFE_MOBILE_CHAT} (Qwen3.5-0.8B) or Qwen3.5-2B on Android.`,
+		maxSafeModel: "mlx-community/Qwen3.5-2B-4bit"
+	};
 	return {
-		startRecording: useCallback(async () => {
-			if (isRecording) return;
-			try {
-				if (streaming && !sttRef.current) {
-					if (!shouldLoad) setShouldLoad(true);
-					setIsLoading(true);
-					const { WhisperSTT } = await import("../stt-Bu-E23Sc.js");
-					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
+		safe: true,
+		risky: false,
+		reason: "Desktop browser has sufficient memory."
 	};
 }
 /**
-* 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",
-*   });
+* Get recommended models based on device memory and capabilities.
+* Helps prevent OOM crashes on low-memory mobile devices.
+*/
+function getRecommendedModels() {
+	const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+	const deviceMemory = typeof navigator !== "undefined" ? navigator.deviceMemory : null;
+	const isMobile = /iPhone|iPad|iPod|Android|Mobile/.test(ua);
+	const availableMB = (deviceMemory ? isMobile ? deviceMemory * .4 : deviceMemory * .6 : 4) * 1024;
+	let chat;
+	let reason;
+	if (availableMB < 600) {
+		chat = "LiquidAI/LFM2.5-350M";
+		reason = "Very low memory device - using smallest model (LFM2.5-350M)";
+	} else if (isMobile && availableMB < 2200) {
+		chat = SAFE_MOBILE_CHAT;
+		reason = "Mobile device - using Qwen3.5-0.8B to stay within the WKWebView memory limit";
+	} else if (availableMB < 2200) {
+		chat = SAFE_MOBILE_CHAT;
+		reason = "Standard model for moderate memory (Qwen3.5-0.8B)";
+	} else {
+		chat = "mlx-community/Qwen3.5-2B-4bit";
+		reason = "High memory available - using Qwen3.5-2B for better quality";
+	}
+	return {
+		chat,
+		tts: "kokoro-82m",
+		stt: "whisper-tiny.en",
+		embedding: "all-MiniLM-L6-v2",
+		reason,
+		deviceMemory,
+		isMobile
+	};
+}
+const SESSION_STORAGE_KEY = "gerbil_session_phase";
+/**
+* Generate a unique session ID for tracking across reloads.
+*/
+function generateSessionId() {
+	return `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+/**
+* Get or create the current session ID.
+*/
+function getSessionId() {
+	if (typeof localStorage === "undefined") return generateSessionId();
+	let sessionId = sessionStorage.getItem("gerbil_session_id");
+	if (!sessionId) {
+		sessionId = generateSessionId();
+		sessionStorage.setItem("gerbil_session_id", sessionId);
+	}
+	return sessionId;
+}
+/**
+* Set the current download/initialization phase.
+* Used to detect if a reload happened during a critical operation.
+*/
+function setDownloadPhase(phase, modelId, progress) {
+	if (typeof localStorage === "undefined") return;
+	const state = {
+		phase,
+		modelId: modelId || null,
+		sessionId: getSessionId(),
+		timestamp: Date.now(),
+		bytesDownloaded: progress?.bytesDownloaded,
+		totalBytes: progress?.totalBytes
+	};
+	localStorage.setItem(SESSION_STORAGE_KEY, JSON.stringify(state));
+}
+/**
+* Get the last known download phase from storage.
+*/
+function getDownloadPhase() {
+	if (typeof localStorage === "undefined") return null;
+	try {
+		const raw = localStorage.getItem(SESSION_STORAGE_KEY);
+		if (!raw) return null;
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+/**
+* Detect if the page reloaded during a model download/initialization.
+* This typically indicates an iOS memory crash.
 *
-*   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>
-*   );
-* }
-* ```
+* @returns Detection result with recommended action
 */
-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-Bu-E23Sc.js");
-				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-CqroPaSK.js");
-				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;
+function detectMemoryCrash() {
+	const lastState = getDownloadPhase();
+	const currentSessionId = getSessionId();
+	if (!lastState) return { crashed: false };
+	const wasInCriticalPhase = [
+		"downloading",
+		"caching",
+		"initializing"
+	].includes(lastState.phase);
+	const sessionChanged = lastState.sessionId !== currentSessionId;
+	const timeSinceCrash = Date.now() - lastState.timestamp;
+	if (wasInCriticalPhase && sessionChanged && timeSinceCrash < 300 * 1e3) {
+		localStorage.removeItem(SESSION_STORAGE_KEY);
+		return {
+			crashed: true,
+			phase: lastState.phase,
+			modelId: lastState.modelId || void 0,
+			timeSinceCrash,
+			recommendation: lastState.modelId && /2b|gemma|vision/i.test(lastState.modelId) ? "The model was too large for your device. Try Qwen3.5-0.8B instead." : "Your device ran out of memory. Try a smaller model or use a desktop browser."
 		};
-	}, [
-		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();
+	}
+	return { crashed: false };
+}
+/**
+* Clear session phase (call when model loads successfully).
+*/
+function clearDownloadPhase() {
+	if (typeof localStorage === "undefined") return;
+	localStorage.removeItem(SESSION_STORAGE_KEY);
+}
+
+//#endregion
+//#region src/browser/download.ts
+/** Chunk size for downloads: 1.5MB (safe for iOS IndexedDB transactions) */
+const CHUNK_SIZE_BYTES = 1.5 * 1024 * 1024;
+/** IndexedDB database name for chunked downloads */
+const DOWNLOAD_DB_NAME = "gerbil-model-chunks";
+const DOWNLOAD_DB_VERSION = 1;
+/**
+* Open (or create) the IndexedDB for chunked downloads.
+*/
+async function openDownloadDB() {
+	return new Promise((resolve, reject) => {
+		const request = indexedDB.open(DOWNLOAD_DB_NAME, DOWNLOAD_DB_VERSION);
+		request.onerror = () => reject(/* @__PURE__ */ new Error(`Failed to open download DB: ${request.error?.message}`));
+		request.onsuccess = () => resolve(request.result);
+		request.onupgradeneeded = (event) => {
+			const db = event.target.result;
+			if (!db.objectStoreNames.contains("manifests")) db.createObjectStore("manifests", { keyPath: "modelId" });
+			if (!db.objectStoreNames.contains("chunks")) db.createObjectStore("chunks");
 		};
-	}, []);
-	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;
+	});
+}
+/**
+* Get download manifest for a model.
+*/
+async function getManifest(db, modelId) {
+	return new Promise((resolve, reject) => {
+		const request = db.transaction("manifests", "readonly").objectStore("manifests").get(modelId);
+		request.onerror = () => reject(/* @__PURE__ */ new Error(`Failed to get manifest: ${request.error?.message}`));
+		request.onsuccess = () => resolve(request.result || null);
+	});
+}
+/**
+* Save download manifest.
+*/
+async function saveManifest(db, manifest) {
+	return new Promise((resolve, reject) => {
+		const request = db.transaction("manifests", "readwrite").objectStore("manifests").put(manifest);
+		request.onerror = () => reject(/* @__PURE__ */ new Error(`Failed to save manifest: ${request.error?.message}`));
+		request.onsuccess = () => resolve();
+	});
+}
+/**
+* Save a single chunk.
+*/
+async function saveChunk(db, modelId, chunkIndex, data) {
+	return new Promise((resolve, reject) => {
+		const store = db.transaction("chunks", "readwrite").objectStore("chunks");
+		const key = `${modelId}-${chunkIndex}`;
+		const request = store.put(data, key);
+		request.onerror = () => reject(/* @__PURE__ */ new Error(`Failed to save chunk ${chunkIndex}: ${request.error?.message}`));
+		request.onsuccess = () => resolve();
+	});
+}
+/**
+* Get a single chunk.
+*/
+async function getChunk(db, modelId, chunkIndex) {
+	return new Promise((resolve, reject) => {
+		const store = db.transaction("chunks", "readonly").objectStore("chunks");
+		const key = `${modelId}-${chunkIndex}`;
+		const request = store.get(key);
+		request.onerror = () => reject(/* @__PURE__ */ new Error(`Failed to get chunk ${chunkIndex}: ${request.error?.message}`));
+		request.onsuccess = () => resolve(request.result || null);
+	});
+}
+/**
+* Delete all chunks and manifest for a model.
+*/
+async function clearModelData(db, modelId) {
+	const manifest = await getManifest(db, modelId);
+	return new Promise((resolve, reject) => {
+		const tx = db.transaction(["manifests", "chunks"], "readwrite");
+		tx.objectStore("manifests").delete(modelId);
+		if (manifest) {
+			const totalChunks = Math.ceil(manifest.totalBytes / manifest.chunkSize);
+			const chunkStore = tx.objectStore("chunks");
+			for (let i = 0; i < totalChunks; i++) chunkStore.delete(`${modelId}-${i}`);
 		}
-		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;
+		tx.oncomplete = () => resolve();
+		tx.onerror = () => reject(/* @__PURE__ */ new Error(`Failed to clear model data: ${tx.error?.message}`));
+	});
+}
+/**
+* Chunked resumable downloader for large model files.
+* Downloads in 1.5MB chunks to avoid iOS memory pressure.
+*/
+async function downloadModelChunked(url, modelId, options = {}) {
+	const { onProgress, signal } = options;
+	setDownloadPhase("downloading", modelId);
+	const db = await openDownloadDB();
+	try {
+		let manifest = await getManifest(db, modelId);
+		const headResponse = await fetch(url, {
+			method: "HEAD",
+			signal
 		});
-	}, []);
-	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);
+		if (!headResponse.ok) throw new Error(`HEAD request failed: ${headResponse.status} ${headResponse.statusText}`);
+		const contentLength = parseInt(headResponse.headers.get("content-length") || "0", 10);
+		const etag = headResponse.headers.get("etag");
+		const acceptRanges = headResponse.headers.get("accept-ranges");
+		if (!contentLength) throw new Error("Server did not provide content-length");
+		if (manifest && manifest.etag !== etag) {
+			console.warn(`Model ${modelId} has been updated (etag mismatch). Clearing cached chunks.`);
+			await clearModelData(db, modelId);
+			manifest = null;
+		}
+		if (!(acceptRanges === "bytes")) {
+			console.warn(`Server doesn't support range requests for ${modelId}. Using regular download.`);
+			db.close();
+			const response = await fetch(url, { signal });
+			if (!response.ok) throw new Error(`Download failed: ${response.status}`);
+			setDownloadPhase("caching", modelId);
+			const buffer = await response.arrayBuffer();
+			setDownloadPhase("ready", modelId);
+			return buffer;
+		}
+		const totalChunks = Math.ceil(contentLength / CHUNK_SIZE_BYTES);
+		if (!manifest) {
+			manifest = {
+				modelId,
+				url,
+				etag,
+				totalBytes: contentLength,
+				chunkSize: CHUNK_SIZE_BYTES,
+				completedChunks: [],
+				createdAt: Date.now(),
+				updatedAt: Date.now()
+			};
+			await saveManifest(db, manifest);
+		}
+		for (let i = 0; i < totalChunks; i++) {
+			if (signal?.aborted) throw new Error("Download aborted");
+			if (manifest.completedChunks.includes(i)) {
+				const bytesDownloaded$1 = manifest.completedChunks.length / totalChunks * contentLength;
+				onProgress?.({
+					phase: "resuming",
+					bytesDownloaded: bytesDownloaded$1,
+					totalBytes: contentLength,
+					percent: Math.round(bytesDownloaded$1 / contentLength * 100)
+				});
+				continue;
 			}
-		}, [
-			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();
+			const start = i * CHUNK_SIZE_BYTES;
+			const end = Math.min(start + CHUNK_SIZE_BYTES - 1, contentLength - 1);
+			const response = await fetch(url, {
+				headers: { Range: `bytes=${start}-${end}` },
+				signal
 			});
-		}, [
-			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
-	};
+			if (response.status !== 206) throw new Error(`Range request failed: ${response.status} (expected 206)`);
+			const chunkData = await response.arrayBuffer();
+			await saveChunk(db, modelId, i, chunkData);
+			manifest.completedChunks.push(i);
+			manifest.updatedAt = Date.now();
+			await saveManifest(db, manifest);
+			const bytesDownloaded = manifest.completedChunks.length * CHUNK_SIZE_BYTES;
+			setDownloadPhase("downloading", modelId, {
+				bytesDownloaded,
+				totalBytes: contentLength
+			});
+			onProgress?.({
+				phase: "downloading",
+				bytesDownloaded: Math.min(bytesDownloaded, contentLength),
+				totalBytes: contentLength,
+				percent: Math.round(manifest.completedChunks.length / totalChunks * 100)
+			});
+			response.body = null;
+		}
+		setDownloadPhase("caching", modelId);
+		onProgress?.({
+			phase: "assembling",
+			bytesDownloaded: contentLength,
+			totalBytes: contentLength,
+			percent: 100
+		});
+		const finalBuffer = new ArrayBuffer(contentLength);
+		const finalView = new Uint8Array(finalBuffer);
+		for (let i = 0; i < totalChunks; i++) {
+			const chunk = await getChunk(db, modelId, i);
+			if (!chunk) throw new Error(`Missing chunk ${i} during assembly`);
+			const offset = i * CHUNK_SIZE_BYTES;
+			finalView.set(new Uint8Array(chunk), offset);
+		}
+		await clearModelData(db, modelId);
+		db.close();
+		setDownloadPhase("ready", modelId);
+		return finalBuffer;
+	} catch (error) {
+		setDownloadPhase("error", modelId);
+		db.close();
+		throw error;
+	}
 }
 /**
-* Check if WebGPU is supported
+* Check if a model has an incomplete download.
 */
-function isWebGPUSupported() {
-	if (typeof navigator === "undefined") return false;
-	return "gpu" in navigator;
+async function hasIncompleteDownload(modelId) {
+	try {
+		const db = await openDownloadDB();
+		const manifest = await getManifest(db, modelId);
+		db.close();
+		if (!manifest) return { incomplete: false };
+		const totalChunks = Math.ceil(manifest.totalBytes / manifest.chunkSize);
+		const completedChunks = manifest.completedChunks.length;
+		if (completedChunks < totalChunks) return {
+			incomplete: true,
+			bytesDownloaded: completedChunks * manifest.chunkSize,
+			totalBytes: manifest.totalBytes,
+			percent: Math.round(completedChunks / totalChunks * 100)
+		};
+		return { incomplete: false };
+	} catch {
+		return { incomplete: false };
+	}
 }
 /**
-* Get WebGPU adapter info
+* Clear incomplete download data for a model.
 */
-async function getWebGPUInfo() {
-	if (!isWebGPUSupported()) return { supported: false };
+async function clearIncompleteDownload(modelId) {
 	try {
-		const adapter = await navigator.gpu.requestAdapter();
-		if (!adapter) return { supported: false };
-		const info = await adapter.requestAdapterInfo();
+		const db = await openDownloadDB();
+		await clearModelData(db, modelId);
+		db.close();
+	} catch {}
+}
+/**
+* Check if there's enough storage quota for a model download.
+* Returns estimated available space and whether download should proceed.
+*/
+async function checkStorageQuota(requiredMB = 500) {
+	if (typeof navigator === "undefined" || !navigator.storage?.estimate) return {
+		ok: true,
+		availableMB: -1,
+		usedMB: -1,
+		quotaMB: -1,
+		message: "Storage API not available"
+	};
+	try {
+		const { quota, usage } = await navigator.storage.estimate();
+		const quotaMB = Math.round((quota || 0) / 1e6);
+		const usedMB = Math.round((usage || 0) / 1e6);
+		const availableMB = quotaMB - usedMB;
+		if (availableMB < requiredMB) return {
+			ok: false,
+			availableMB,
+			usedMB,
+			quotaMB,
+			message: `Need ${requiredMB}MB but only ${availableMB}MB available. Clear browser data or free up space.`
+		};
 		return {
-			supported: true,
-			adapter: info.vendor,
-			device: info.device
+			ok: true,
+			availableMB,
+			usedMB,
+			quotaMB
+		};
+	} catch (e) {
+		return {
+			ok: true,
+			availableMB: -1,
+			usedMB: -1,
+			quotaMB: -1,
+			message: `Storage check failed: ${e.message}`
 		};
-	} catch {
-		return { supported: false };
 	}
 }
-var browser_default = {
-	isWebGPUSupported,
-	getWebGPUInfo,
-	createGerbilWorker,
-	playAudio,
-	createAudioPlayer
-};
 
 //#endregion
-export { BUILTIN_MODELS, createAudioPlayer, createGerbilWorker, browser_default as default, getWebGPUInfo, isWebGPUSupported, playAudio, useChat, useCompletion, useSpeech, useVoiceChat, useVoiceInput };
+export { BUILTIN_MODELS, CHUNK_SIZE_BYTES, DOWNLOAD_DB_NAME, MODEL_SIZES, SESSION_STORAGE_KEY, canCacheModel, checkStorageQuota, clearDownloadPhase, clearIncompleteDownload, createAudioPlayer, detectMemoryCrash, downloadModelChunked, getDownloadPhase, getInstallGuidance, getRecommendedModels, getStorageStatus, hasIncompleteDownload, isIOS, isModelSafeForDevice, isStandalone, playAudio, requestPersistentStorage, setDownloadPhase };
 //# sourceMappingURL=index.js.map