@tryhamster/gerbil 1.0.0-rc.22 → 1.0.0-rc.24

package/dist/browser/index.js

@@ -257,21 +257,32 @@ async function createGerbilWorker(options = {}) {
             modelId.toLowerCase().includes("vision") ||
             modelId.toLowerCase().includes("vlm");
 
-          const dtype = options.dtype || "q4f16";
+          // Detect mobile - must use q4 (not q4f16) due to memory/pagefile limitations
+          const isMobile = /iPhone|iPad|Android|Mobile/i.test(navigator.userAgent);
+          
+          // q4f16 requires more memory and float16 GPU support
+          // Mobile devices MUST use q4 - pagefile cannot handle q4f16
+          let dtype = isMobile ? "q4" : (options.dtype || "q4f16");
+          
+          if (isMobile && options.dtype === "q4f16") {
+            console.warn("Mobile detected: forcing q4 instead of q4f16 (memory constraints)");
+            dtype = "q4";
+          }
           let device = options.device || "webgpu";
           let usedFallback = false;
 
           // Helper to load model with WASM fallback
           async function loadWithFallback(loadFn, opts) {
             try {
-              return await loadFn({ ...opts, device });
+              return await loadFn({ ...opts, device, dtype });
             } catch (webgpuError) {
               if (device === "webgpu") {
                 console.warn("WebGPU failed, falling back to WASM:", webgpuError.message);
                 self.postMessage({ status: "fallback", backend: "wasm", reason: webgpuError.message });
                 device = "wasm";
+                dtype = "q4"; // WASM doesn't support q4f16
                 usedFallback = true;
-                return await loadFn({ ...opts, device: "wasm" });
+                return await loadFn({ ...opts, device: "wasm", dtype: "q4" });
               }
               throw webgpuError;
             }
@@ -279,7 +290,7 @@ async function createGerbilWorker(options = {}) {
 
           if (this.isVision) {
             // Load vision model components
-            // Note: Don't specify dtype for vision models - let transformers.js pick defaults
+            // On mobile, force q4 to avoid memory issues
             if (!this.processor) {
               this.processor = await AutoProcessor.from_pretrained(modelId, {
                 progress_callback: progressCallback,
@@ -288,7 +299,7 @@ async function createGerbilWorker(options = {}) {
             if (!this.visionModel) {
               this.visionModel = await loadWithFallback(
                 (opts) => AutoModelForImageTextToText.from_pretrained(modelId, opts),
-                { progress_callback: progressCallback }
+                { dtype, progress_callback: progressCallback }
               );
             }
             return { 
@@ -755,6 +766,13 @@ function useChat(options = {}) {
 		setIsLoading(true);
 		setShouldLoad(true);
 	}, [isLoading]);
+	useEffect(() => {
+		const crash = detectMemoryCrash();
+		if (crash.crashed) {
+			setError(crash.recommendation || "Previous model load failed due to device memory limits.");
+			onError?.(crash.recommendation || "Previous model load failed");
+		}
+	}, []);
 	useEffect(() => {
 		if (!shouldLoad) return;
 		if (!isWebGPUSupported()) {
@@ -764,13 +782,27 @@ function useChat(options = {}) {
 			onError?.(gpuError);
 			return;
 		}
+		const safetyCheck = isModelSafeForDevice(model);
+		if (!safetyCheck.safe) {
+			setError(safetyCheck.reason);
+			setIsLoading(false);
+			onError?.(safetyCheck.reason);
+			return;
+		}
 		mountedRef.current = true;
+		setDownloadPhase("downloading", model);
 		createGerbilWorker({
 			modelId: model,
 			onProgress: (p) => {
 				if (!mountedRef.current) return;
 				setLoadingProgress(p);
+				if (p.status === "downloading" && p.progress !== void 0) setDownloadPhase("downloading", model, {
+					bytesDownloaded: p.progress,
+					totalBytes: 100
+				});
+				else if (p.status === "loading") setDownloadPhase("initializing", model);
 				if (p.status === "ready") {
+					clearDownloadPhase();
 					setIsLoading(false);
 					setIsReady(true);
 					onReady?.();
@@ -788,6 +820,7 @@ function useChat(options = {}) {
 			},
 			onError: (err) => {
 				if (!mountedRef.current) return;
+				setDownloadPhase("error", model);
 				setError(err);
 				setIsGenerating(false);
 				onError?.(err);
@@ -797,6 +830,7 @@ function useChat(options = {}) {
 			else worker.terminate();
 		}).catch((err) => {
 			if (mountedRef.current) {
+				setDownloadPhase("error", model);
 				setError(err.message);
 				setIsLoading(false);
 				onError?.(err.message);
@@ -1024,6 +1058,13 @@ function useCompletion(options = {}) {
 		setIsLoading(true);
 		setShouldLoad(true);
 	}, [isLoading]);
+	useEffect(() => {
+		const crash = detectMemoryCrash();
+		if (crash.crashed) {
+			setError(crash.recommendation || "Previous model load failed due to device memory limits.");
+			onError?.(crash.recommendation || "Previous model load failed");
+		}
+	}, []);
 	useEffect(() => {
 		if (!shouldLoad) return;
 		if (!isWebGPUSupported()) {
@@ -1033,13 +1074,27 @@ function useCompletion(options = {}) {
 			onError?.(gpuError);
 			return;
 		}
+		const safetyCheck = isModelSafeForDevice(model);
+		if (!safetyCheck.safe) {
+			setError(safetyCheck.reason);
+			setIsLoading(false);
+			onError?.(safetyCheck.reason);
+			return;
+		}
 		mountedRef.current = true;
+		setDownloadPhase("downloading", model);
 		createGerbilWorker({
 			modelId: model,
 			onProgress: (p) => {
 				if (!mountedRef.current) return;
 				setLoadingProgress(p);
+				if (p.status === "downloading" && p.progress !== void 0) setDownloadPhase("downloading", model, {
+					bytesDownloaded: p.progress,
+					totalBytes: 100
+				});
+				else if (p.status === "loading") setDownloadPhase("initializing", model);
 				if (p.status === "ready") {
+					clearDownloadPhase();
 					setIsLoading(false);
 					setIsReady(true);
 					onReady?.();
@@ -1059,6 +1114,7 @@ function useCompletion(options = {}) {
 			},
 			onError: (err) => {
 				if (!mountedRef.current) return;
+				setDownloadPhase("error", model);
 				setError(err);
 				setIsGenerating(false);
 				onError?.(err);
@@ -1068,6 +1124,7 @@ function useCompletion(options = {}) {
 			else worker.terminate();
 		}).catch((err) => {
 			if (mountedRef.current) {
+				setDownloadPhase("error", model);
 				setError(err.message);
 				setIsLoading(false);
 				onError?.(err.message);
@@ -1434,12 +1491,12 @@ const TTS_WORKER_CODE = `
           // Load Supertonic using transformers.js pipeline with WASM fallback
           let device = "webgpu";
           try {
-            ttsInstance = await pipeline("text-to-speech", repo, {
+          ttsInstance = await pipeline("text-to-speech", repo, {
               device,
-              progress_callback: (progress) => {
-                self.postMessage({ type: "progress", payload: progress });
-              },
-            });
+            progress_callback: (progress) => {
+              self.postMessage({ type: "progress", payload: progress });
+            },
+          });
           } catch (webgpuError) {
             console.warn("WebGPU failed for TTS, falling back to WASM:", webgpuError.message);
             self.postMessage({ type: "fallback", payload: { backend: "wasm", reason: webgpuError.message } });
@@ -1480,12 +1537,26 @@ const TTS_WORKER_CODE = `
           const kokoroModule = await import("https://cdn.jsdelivr.net/npm/kokoro-js@1.2.1/dist/kokoro.web.min.js");
           const { KokoroTTS } = kokoroModule;
           
+          // Try WebGPU first, fallback to WASM
+          try {
           kokoroTTS = await KokoroTTS.from_pretrained(repo, {
             dtype: "fp32",
+              device: "webgpu",
+              progress_callback: (progress) => {
+                self.postMessage({ type: "progress", payload: progress });
+              },
+            });
+          } catch (webgpuError) {
+            console.warn("WebGPU failed for Kokoro TTS, falling back:", webgpuError.message);
+            self.postMessage({ type: "fallback", payload: { backend: "wasm", reason: webgpuError.message } });
+            kokoroTTS = await KokoroTTS.from_pretrained(repo, {
+              dtype: "fp32",
+              device: "wasm",
             progress_callback: (progress) => {
               self.postMessage({ type: "progress", payload: progress });
             },
           });
+          }
         }
         
         self.postMessage({ type: "ready" });
@@ -1604,10 +1675,18 @@ function useSpeech(options = {}) {
 		setIsLoading(true);
 		setShouldLoad(true);
 	}, [isLoading]);
+	useEffect(() => {
+		const crash = detectMemoryCrash();
+		if (crash.crashed) {
+			setError(crash.recommendation || "Previous model load failed due to device memory limits.");
+			onError?.(crash.recommendation || "Previous model load failed");
+		}
+	}, []);
 	useEffect(() => {
 		if (!shouldLoad) return;
 		mountedRef.current = true;
 		modelIdRef.current = modelId;
+		setDownloadPhase("downloading", modelId);
 		const config = TTS_MODELS[modelId];
 		setLoadingProgress({
 			status: "loading",
@@ -1624,6 +1703,7 @@ function useSpeech(options = {}) {
 				progress: Math.round(payload.progress || 0)
 			});
 			if (type === "ready") {
+				clearDownloadPhase();
 				setIsLoading(false);
 				setIsReady(true);
 				setLoadingProgress({ status: "ready" });
@@ -1646,6 +1726,7 @@ function useSpeech(options = {}) {
 				playAudioData(audio, sampleRate);
 			}
 			if (type === "error") {
+				setDownloadPhase("error", modelId);
 				const errorMsg = payload;
 				setError(errorMsg);
 				setIsLoading(false);
@@ -1659,6 +1740,7 @@ function useSpeech(options = {}) {
 		};
 		worker.onerror = (err) => {
 			if (!mountedRef.current) return;
+			setDownloadPhase("error", modelId);
 			let errorMsg = err.message || "";
 			if (!errorMsg || errorMsg === "Script error.") errorMsg = getWebGPUErrorMessage();
 			setError(errorMsg);
@@ -1916,12 +1998,12 @@ const STT_WORKER_CODE = `
         // Load Whisper model with WASM fallback
         let device = "webgpu";
         try {
-          sttPipeline = await pipeline("automatic-speech-recognition", model, {
+        sttPipeline = await pipeline("automatic-speech-recognition", model, {
             device,
-            progress_callback: (progress) => {
-              self.postMessage({ type: "progress", payload: progress });
-            },
-          });
+          progress_callback: (progress) => {
+            self.postMessage({ type: "progress", payload: progress });
+          },
+        });
         } catch (webgpuError) {
           console.warn("WebGPU failed for STT, falling back to WASM:", webgpuError.message);
           self.postMessage({ type: "fallback", payload: { backend: "wasm", reason: webgpuError.message } });
@@ -2040,9 +2122,17 @@ function useVoiceInput(options = {}) {
 			"whisper-small.en": "onnx-community/whisper-small.en"
 		}[modelId] || modelId;
 	};
+	useEffect(() => {
+		const crash = detectMemoryCrash();
+		if (crash.crashed) {
+			setError(crash.recommendation || "Previous model load failed due to device memory limits.");
+			onError?.(crash.recommendation || "Previous model load failed");
+		}
+	}, []);
 	useEffect(() => {
 		if (!shouldLoad || isReady) return;
 		mountedRef.current = true;
+		setDownloadPhase("downloading", model);
 		setIsLoading(true);
 		setLoadingProgress({
 			status: "loading",
@@ -2068,6 +2158,7 @@ function useVoiceInput(options = {}) {
 				onProgress?.(progress);
 			}
 			if (type === "ready") {
+				clearDownloadPhase();
 				setIsReady(true);
 				setIsLoading(false);
 				setLoadingProgress({ status: "ready" });
@@ -2084,6 +2175,7 @@ function useVoiceInput(options = {}) {
 				}
 			}
 			if (type === "error") {
+				setDownloadPhase("error", model);
 				const errMsg = payload;
 				setError(errMsg);
 				setIsLoading(false);
@@ -2106,6 +2198,7 @@ function useVoiceInput(options = {}) {
 		};
 		worker.onerror = (err) => {
 			if (!mountedRef.current) return;
+			setDownloadPhase("error", model);
 			let errMsg = err.message || "";
 			if (!errMsg || errMsg === "Script error.") errMsg = getWebGPUErrorMessage();
 			setError(errMsg);
@@ -3027,6 +3120,13 @@ function useEmbedding(options = {}) {
 		if (magnitude === 0) return 0;
 		return dotProduct / magnitude;
 	}, []);
+	useEffect(() => {
+		const crash = detectMemoryCrash();
+		if (crash.crashed) {
+			setError(crash.recommendation || "Previous model load failed due to device memory limits.");
+			onError?.(crash.recommendation || "Previous model load failed");
+		}
+	}, []);
 	const load = useCallback(() => {
 		if (isReady && workerRef.current) return Promise.resolve();
 		if (loadRequestedRef.current && readyPromiseRef.current) return readyPromiseRef.current;
@@ -3036,6 +3136,7 @@ function useEmbedding(options = {}) {
 			status: "loading",
 			message: "Loading embedding model..."
 		});
+		setDownloadPhase("downloading", model);
 		readyPromiseRef.current = new Promise((resolve) => {
 			readyResolveRef.current = resolve;
 		});
@@ -3050,18 +3151,21 @@ function useEmbedding(options = {}) {
 					progress: Math.round(payload.loaded / payload.total * 100)
 				});
 			} else if (type === "ready") {
+				clearDownloadPhase();
 				setIsLoading(false);
 				setIsReady(true);
 				setLoadingProgress({ status: "ready" });
 				readyResolveRef.current?.();
 				onReady?.();
 			} else if (type === "error") {
+				setDownloadPhase("error", model);
 				setIsLoading(false);
 				setError(payload);
 				onError?.(payload);
 			}
 		});
 		worker.onerror = (err) => {
+			setDownloadPhase("error", model);
 			setIsLoading(false);
 			let errMsg = err.message || "";
 			if (!errMsg || errMsg === "Script error.") errMsg = getWebGPUErrorMessage();
@@ -3566,11 +3670,11 @@ async function getBrowserDiagnostics() {
 	} catch {
 		moduleWorkers = false;
 	}
-	let indexedDB = false;
+	let indexedDB$1 = false;
 	try {
-		indexedDB = typeof window !== "undefined" && "indexedDB" in window;
+		indexedDB$1 = typeof window !== "undefined" && "indexedDB" in window;
 	} catch {
-		indexedDB = false;
+		indexedDB$1 = false;
 	}
 	return {
 		browser,
@@ -3583,7 +3687,7 @@ async function getBrowserDiagnostics() {
 		webgpuExpected,
 		webgpu,
 		moduleWorkers,
-		indexedDB
+		indexedDB: indexedDB$1
 	};
 }
 /**
@@ -3621,6 +3725,370 @@ function getRecommendedModels() {
 	};
 }
 /**
+* Maximum safe model sizes for iOS devices (in MB).
+* Based on WKWebView effective memory limit of ~200-400MB.
+*/
+const IOS_MODEL_LIMITS = {
+	safe: ["smollm2-135m", "smollm2-360m"],
+	risky: ["qwen3-0.6b"],
+	blocked: ["qwen3-1.7b", "qwen3-4b"],
+	maxBudgetMB: 350
+};
+/**
+* Check if a model is safe to load on the current device.
+* Returns guidance specific to iOS memory constraints.
+*/
+function isModelSafeForDevice(modelId) {
+	const ua = typeof navigator !== "undefined" ? navigator.userAgent : "";
+	const isIOS = /iPhone|iPad|iPod/.test(ua);
+	const isIOSChrome = isIOS && /CriOS/.test(ua);
+	const deviceMemory = typeof navigator !== "undefined" ? navigator.deviceMemory : null;
+	const normalizedId = modelId.toLowerCase().replace(/[^a-z0-9]/g, "-");
+	if (isIOS) {
+		if (IOS_MODEL_LIMITS.blocked.some((m) => normalizedId.includes(m.toLowerCase().replace(/[^a-z0-9]/g, "-")))) return {
+			safe: false,
+			reason: `Model ${modelId} is too large for iOS devices${isIOSChrome ? " (iOS Chrome uses WKWebView, same limits as Safari)" : ""}. WKWebView memory limit (~300-400MB) will cause crashes.`,
+			recommendation: "Use smollm2-360m or qwen3-0.6b on iOS. For larger models, use desktop.",
+			maxSafeModel: "qwen3-0.6b"
+		};
+		if (IOS_MODEL_LIMITS.risky.some((m) => normalizedId.includes(m.toLowerCase().replace(/[^a-z0-9]/g, "-")))) {
+			if (!(deviceMemory && deviceMemory >= 4)) return {
+				safe: false,
+				reason: `Model ${modelId} may crash on older iOS devices. Your device reports ${deviceMemory || "unknown"}GB RAM.`,
+				recommendation: "Use smollm2-360m for reliable performance, or try on iPhone 14+ / iPad Pro.",
+				maxSafeModel: "smollm2-360m"
+			};
+			return {
+				safe: true,
+				reason: `Model ${modelId} should work on your high-memory iOS device, but may be slow.`
+			};
+		}
+		return {
+			safe: true,
+			reason: "Model is within iOS memory limits."
+		};
+	}
+	if (/Android/.test(ua)) {
+		if (normalizedId.includes("qwen3-4b") || normalizedId.includes("7b")) return {
+			safe: false,
+			reason: `Model ${modelId} is very large and may crash on Android devices.`,
+			recommendation: "Use qwen3-1.7b or smaller on Android.",
+			maxSafeModel: "qwen3-1.7b"
+		};
+	}
+	return {
+		safe: true,
+		reason: "Desktop browser has sufficient memory."
+	};
+}
+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.
+*
+* @returns Detection result with recommended action
+*/
+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?.includes("1.7b") ? "The model was too large for your device. Try smollm2-360m or qwen3-0.6b instead." : "Your device ran out of memory. Try a smaller model or use a desktop browser."
+		};
+	}
+	return { crashed: false };
+}
+/**
+* Clear session phase (call when model loads successfully).
+*/
+function clearDownloadPhase() {
+	if (typeof localStorage === "undefined") return;
+	localStorage.removeItem(SESSION_STORAGE_KEY);
+}
+/** 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");
+		};
+	});
+}
+/**
+* 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}`);
+		}
+		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
+		});
+		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;
+			}
+			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
+			});
+			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 a model has an incomplete download.
+*/
+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 };
+	}
+}
+/**
+* Clear incomplete download data for a model.
+*/
+async function clearIncompleteDownload(modelId) {
+	try {
+		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.
 */
@@ -3668,6 +4136,14 @@ var browser_default = {
 	getBrowserDiagnostics,
 	getRecommendedModels,
 	checkStorageQuota,
+	isModelSafeForDevice,
+	setDownloadPhase,
+	getDownloadPhase,
+	detectMemoryCrash,
+	clearDownloadPhase,
+	downloadModelChunked,
+	hasIncompleteDownload,
+	clearIncompleteDownload,
 	createGerbilWorker,
 	playAudio,
 	createAudioPlayer,
@@ -3678,5 +4154,5 @@ var browser_default = {
 };
 
 //#endregion
-export { BUILTIN_MODELS, checkStorageQuota, checkWebGPUCapabilities, checkWebGPUReady, createAudioPlayer, createGerbilWorker, browser_default as default, getBrowserDiagnostics, getRecommendedModels, getWebGPUInfo, isWebGPUSupported, playAudio, preloadChatModel, preloadEmbeddingModel, preloadSTTModel, preloadTTSModel, useChat, useCompletion, useEmbedding, useSpeech, useVoiceChat, useVoiceInput };
+export { BUILTIN_MODELS, checkStorageQuota, checkWebGPUCapabilities, checkWebGPUReady, clearDownloadPhase, clearIncompleteDownload, createAudioPlayer, createGerbilWorker, browser_default as default, detectMemoryCrash, downloadModelChunked, getBrowserDiagnostics, getDownloadPhase, getRecommendedModels, getWebGPUInfo, hasIncompleteDownload, isModelSafeForDevice, isWebGPUSupported, playAudio, preloadChatModel, preloadEmbeddingModel, preloadSTTModel, preloadTTSModel, setDownloadPhase, useChat, useCompletion, useEmbedding, useSpeech, useVoiceChat, useVoiceInput };
 //# sourceMappingURL=index.js.map