@dr33m/react-native-litert-lm 0.5.0

package/src/__tests__/modelFactory.test.ts

@@ -0,0 +1,153 @@
+import { createLLM } from '../modelFactory';
+import { mockLiteRTLM } from '../__mocks__/react-native-nitro-modules';
+
+describe('modelFactory Security & Proxy Unit Tests', () => {
+  let llm: ReturnType<typeof createLLM>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    llm = createLLM({ enableMemoryTracking: true });
+  });
+
+  it('should block insecure HTTP downloads', async () => {
+    await expect(llm.loadModel('http://example.com/model.litertlm'))
+      .rejects.toThrow('Insecure HTTP URLs are not allowed for model downloads');
+  });
+
+  it('should allow secure HTTPS downloads and strip query parameters', async () => {
+    await llm.loadModel('https://example.com/model.litertlm?token=123');
+
+    expect(mockLiteRTLM.downloadModel).toHaveBeenCalledWith(
+      'https://example.com/model.litertlm?token=123',
+      'model.litertlm',
+      expect.any(Function)
+    );
+    expect(mockLiteRTLM.loadModel).toHaveBeenCalledWith('/mock/path/model.litertlm', undefined);
+  });
+
+  it('should throw an error for invalid model URL', async () => {
+    await expect(llm.loadModel('https://example.com/'))
+      .rejects.toThrow('Invalid model URL: https://example.com/');
+  });
+
+  it('should successfully proxy sendMessage and record memory metrics', async () => {
+    const response = await llm.sendMessage("Test prompt");
+
+    expect(response).toBe("Mock token");
+    expect(mockLiteRTLM.execute).toHaveBeenCalledWith(
+      [{ type: "text", text: "Test prompt" }],
+      undefined,
+    );
+    expect(mockLiteRTLM.getMemoryUsage).toHaveBeenCalled();
+    expect(llm.memoryTracker?.getSnapshotCount()).toBe(1); // sendMessage records one
+  });
+
+  it('should successfully proxy resetConversation and record memory metrics', async () => {
+    await llm.resetConversation();
+
+    expect(mockLiteRTLM.resetConversation).toHaveBeenCalled();
+    expect(mockLiteRTLM.getMemoryUsage).toHaveBeenCalled();
+  });
+
+  it('should successfully proxy sendMessageAsync and record memory metrics when done', async () => {
+    const onToken = jest.fn();
+    await llm.sendMessageAsync("Async prompt", onToken);
+
+    expect(onToken).toHaveBeenCalledWith("Mock ", false);
+    expect(onToken).toHaveBeenCalledWith("token", true);
+    expect(mockLiteRTLM.execute).toHaveBeenCalledWith(
+      [{ type: "text", text: "Async prompt" }],
+      expect.any(Function),
+    );
+    expect(mockLiteRTLM.getMemoryUsage).toHaveBeenCalled();
+  });
+
+  it('should successfully proxy sendMessageWithImageAsync and record memory metrics when done', async () => {
+    const onToken = jest.fn();
+    await llm.sendMessageWithImageAsync("Vision prompt", "/path/to/image.jpg", onToken);
+
+    expect(onToken).toHaveBeenCalledWith("Mock vision ", false);
+    expect(onToken).toHaveBeenCalledWith("token", true);
+    expect(mockLiteRTLM.execute).toHaveBeenCalledWith(
+      [
+        { type: "text", text: "Vision prompt" },
+        { type: "image", path: "/path/to/image.jpg" },
+      ],
+      expect.any(Function),
+    );
+    expect(mockLiteRTLM.getMemoryUsage).toHaveBeenCalled();
+  });
+
+  it('should successfully proxy sendMessageWithAudioAsync and record memory metrics when done', async () => {
+    const onToken = jest.fn();
+    await llm.sendMessageWithAudioAsync("Audio prompt", "/path/to/audio.wav", onToken);
+
+    expect(onToken).toHaveBeenCalledWith("Mock audio ", false);
+    expect(onToken).toHaveBeenCalledWith("token", true);
+    expect(mockLiteRTLM.execute).toHaveBeenCalledWith(
+      [
+        { type: "text", text: "Audio prompt" },
+        { type: "audio", path: "/path/to/audio.wav" },
+      ],
+      expect.any(Function),
+    );
+    expect(mockLiteRTLM.getMemoryUsage).toHaveBeenCalled();
+  });
+
+  it('should successfully access memoryTracker and getSnapshots when memory tracking is enabled', () => {
+    expect(llm.memoryTracker).toBeDefined();
+    expect(llm.memoryTracker?.getCapacity()).toBe(256);
+  });
+
+  it('should not initialize memoryTracker when enableMemoryTracking option is false', () => {
+    const untrackedLLM = createLLM({ enableMemoryTracking: false });
+    expect(untrackedLLM.memoryTracker).toBeUndefined();
+  });
+
+  it('should forward maxContextTokens and maxOutputTokens config to native loadModel', async () => {
+    const config = {
+      backend: 'cpu' as const,
+      maxContextTokens: 8192,
+      maxOutputTokens: 2048,
+    };
+
+    await llm.loadModel('/local/path/model.litertlm', config);
+
+    expect(mockLiteRTLM.loadModel).toHaveBeenCalledWith(
+      '/local/path/model.litertlm',
+      config
+    );
+  });
+
+  it('should forward legacy maxTokens config to native loadModel for backward compat', async () => {
+    const config = {
+      backend: 'cpu' as const,
+      maxTokens: 512,
+    };
+
+    await llm.loadModel('/local/path/model.litertlm', config);
+
+    expect(mockLiteRTLM.loadModel).toHaveBeenCalledWith(
+      '/local/path/model.litertlm',
+      config
+    );
+  });
+
+  it('should forward execute call exactly to native execute', async () => {
+    const parts = [
+      { type: 'image' as const, path: '/path/to/image.jpg', imageBuffer: new ArrayBuffer(10) }
+    ];
+    await llm.execute(parts);
+    expect(mockLiteRTLM.execute).toHaveBeenCalledWith(parts, undefined);
+  });
+
+  it('should strip file:// prefix from paths in execute parts before forwarding to native execute', async () => {
+    const parts = [
+      { type: 'image' as const, path: 'file:///path/to/image.jpg', imageBuffer: new ArrayBuffer(10) }
+    ];
+    await llm.execute(parts);
+    expect(mockLiteRTLM.execute).toHaveBeenCalledWith([
+      { type: 'image' as const, path: '/path/to/image.jpg', imageBuffer: expect.any(ArrayBuffer) }
+    ], undefined);
+  });
+});

package/src/__tests__/modelPath.test.ts

@@ -0,0 +1,14 @@
+import { extractFileName, resolveModelFileName } from "../modelPath";
+
+describe("modelPath", () => {
+  it("strips query strings from URLs", () => {
+    expect(extractFileName("https://example.com/model.litertlm?token=abc")).toBe(
+      "model.litertlm",
+    );
+  });
+
+  it("resolveModelFileName uses basename for paths and URLs", () => {
+    expect(resolveModelFileName("/data/models/foo.litertlm")).toBe("foo.litertlm");
+    expect(resolveModelFileName("bare-name.bin")).toBe("bare-name.bin");
+  });
+});

package/src/__tests__/modelRegistry.test.ts

@@ -0,0 +1,73 @@
+import { ModelRegistry } from '../modelRegistry';
+import { mockModelStore } from '../__mocks__/react-native-nitro-modules';
+
+describe('ModelRegistry Unit Tests', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('isCached should query native store correctly', () => {
+    mockModelStore.isCached.mockReturnValueOnce(true);
+    const result = ModelRegistry.isCached('https://example.com/test-model.litertlm');
+    expect(mockModelStore.isCached).toHaveBeenCalledWith('test-model.litertlm');
+    expect(result).toBe(true);
+  });
+
+  it('getFilePath should return cached path', () => {
+    mockModelStore.getFilePath.mockReturnValueOnce('/caches/test.bin');
+    const path = ModelRegistry.getFilePath('test.bin');
+    expect(mockModelStore.getFilePath).toHaveBeenCalledWith('test.bin');
+    expect(path).toBe('/caches/test.bin');
+  });
+
+  it('listCachedFiles should delegate to native', () => {
+    const mockFiles = [
+      {
+        fileName: 'model.bin',
+        absolutePath: '/caches/model.bin',
+        sizeBytes: 1000,
+        lastModifiedMs: 12345,
+      },
+    ];
+    mockModelStore.listCachedFiles.mockReturnValueOnce(mockFiles as any);
+    const files = ModelRegistry.listCachedFiles();
+    expect(mockModelStore.listCachedFiles).toHaveBeenCalled();
+    expect(files).toEqual(mockFiles);
+  });
+
+  it('deleteFile should delegate delete to native', () => {
+    ModelRegistry.deleteFile('https://example.com/model.bin?q=1');
+    expect(mockModelStore.deleteFile).toHaveBeenCalledWith('model.bin');
+  });
+
+  it('resolveModel should throw error on HTTP urls', async () => {
+    await expect(ModelRegistry.resolveModel('http://example.com/model.bin'))
+      .rejects.toThrow('Insecure HTTP URLs are not allowed for model downloads');
+  });
+
+  it('resolveModel should download HTTPS urls', async () => {
+    mockModelStore.downloadFile.mockResolvedValueOnce('/downloaded/model.bin');
+    const path = await ModelRegistry.resolveModel('https://example.com/model.bin', {
+      headers: { Authorization: 'Bearer test' },
+    });
+    expect(mockModelStore.downloadFile).toHaveBeenCalledWith(
+      'https://example.com/model.bin',
+      'model.bin',
+      JSON.stringify({ Authorization: 'Bearer test' }),
+      expect.any(Function)
+    );
+    expect(path).toBe('/downloaded/model.bin');
+  });
+
+  it('resolveModel should return local paths directly', async () => {
+    const path = await ModelRegistry.resolveModel('/local/path/model.bin');
+    expect(mockModelStore.downloadFile).not.toHaveBeenCalled();
+    expect(path).toBe('/local/path/model.bin');
+  });
+
+  it('resolveModel should strip file:// prefix from local paths', async () => {
+    const path = await ModelRegistry.resolveModel('file:///local/path/model.bin');
+    expect(mockModelStore.downloadFile).not.toHaveBeenCalled();
+    expect(path).toBe('/local/path/model.bin');
+  });
+});

package/src/hooks.ts

@@ -0,0 +1,234 @@
+import { useState, useEffect, useRef, useCallback, useMemo } from "react";
+import { LLMConfig } from "./index";
+import { createLLM } from "./modelFactory";
+import type { LiteRTLMInstance } from "./modelFactory";
+import type { MemoryTracker, MemoryTrackerSummary } from "./memoryTracker";
+import { ModelRegistry } from "./modelRegistry";
+import { extractFileName } from "./modelPath";
+
+export interface UseModelConfig extends LLMConfig {
+  autoLoad?: boolean;
+  /**
+   * Enable memory tracking using native ArrayBuffers (v0.35+).
+   * When enabled, memory usage is tracked after each inference call
+   * using `NitroModules.createNativeArrayBuffer()` for zero-copy storage.
+   * @default false
+   */
+  enableMemoryTracking?: boolean;
+  /**
+   * Maximum number of memory snapshots to store.
+   * Each snapshot uses 32 bytes of native memory.
+   * @default 256
+   */
+  maxMemorySnapshots?: number;
+}
+
+export interface UseModelResult {
+  model: LiteRTLMInstance | null;
+  isReady: boolean;
+  isGenerating: boolean;
+  downloadProgress: number;
+  error: string | null;
+  generate: (prompt: string) => Promise<import("./specs/LiteRTLM.nitro").ExecuteResult>;
+  reset: () => void;
+  /**
+   * Delete the model file. If no fileName is provided, derives it from
+   * the URL/path passed to useModel.
+   */
+  deleteModel: (fileName?: string) => Promise<void>;
+  load: () => Promise<void>;
+  /**
+   * Memory tracker instance (available when enableMemoryTracking is true).
+   * Uses native ArrayBuffers allocated via `NitroModules.createNativeArrayBuffer()`
+   * for efficient, zero-copy memory usage tracking.
+   */
+  memoryTracker: MemoryTracker | null;
+  /**
+   * Current memory tracking summary (null if tracking is disabled).
+   * Updates automatically after each inference call.
+   */
+  memorySummary: MemoryTrackerSummary | null;
+}
+
+export function useModel(
+  pathOrUrl: string,
+  config?: UseModelConfig,
+): UseModelResult {
+  const modelRef = useRef<LiteRTLMInstance | null>(null);
+  const [isReady, setIsReady] = useState(false);
+  const [isGenerating, setIsGenerating] = useState(false);
+  const [downloadProgress, setDownloadProgress] = useState(0);
+  const [error, setError] = useState<string | null>(null);
+  const [memorySummary, setMemorySummary] =
+    useState<MemoryTrackerSummary | null>(null);
+
+  // Destructure config into primitive values for stable dependency arrays.
+  // This prevents infinite re-render loops when consumers pass inline config
+  // objects (e.g. useModel(url, { backend: 'cpu' })) without useMemo.
+  const autoLoad = config?.autoLoad ?? true;
+  const enableMemoryTracking = config?.enableMemoryTracking ?? false;
+  const maxMemorySnapshots = config?.maxMemorySnapshots ?? 256;
+  const backend = config?.backend;
+  const systemPrompt = config?.systemPrompt;
+  const maxTokens = config?.maxTokens;
+  const maxContextTokens = config?.maxContextTokens;
+  const maxOutputTokens = config?.maxOutputTokens;
+  const temperature = config?.temperature;
+  const topK = config?.topK;
+  const topP = config?.topP;
+  const multimodal = config?.multimodal;
+  const tools = config?.tools;
+  const enableSpeculativeDecoding = config?.enableSpeculativeDecoding;
+  const enableThinking = config?.enableThinking;
+  const toolsKey = tools ? JSON.stringify(tools) : undefined;
+
+  // Build a stable config object from the destructured primitives
+  const nativeConfig = useMemo<LLMConfig>(
+    () => ({
+      ...(backend !== undefined && { backend }),
+      ...(systemPrompt !== undefined && { systemPrompt }),
+      ...(maxTokens !== undefined && { maxTokens }),
+      ...(maxContextTokens !== undefined && { maxContextTokens }),
+      ...(maxOutputTokens !== undefined && { maxOutputTokens }),
+      ...(temperature !== undefined && { temperature }),
+      ...(topK !== undefined && { topK }),
+      ...(topP !== undefined && { topP }),
+      ...(multimodal !== undefined && { multimodal }),
+      ...(tools !== undefined && { tools }),
+      ...(enableSpeculativeDecoding !== undefined && {
+        enableSpeculativeDecoding,
+      }),
+      ...(enableThinking !== undefined && { enableThinking }),
+    }),
+    [
+      backend,
+      systemPrompt,
+      maxTokens,
+      maxContextTokens,
+      maxOutputTokens,
+      temperature,
+      topK,
+      topP,
+      multimodal,
+      toolsKey,
+      enableSpeculativeDecoding,
+      enableThinking,
+    ],
+  );
+
+  /**
+   * Refresh memory summary from the tracker's native buffer.
+   */
+  const refreshMemorySummary = useCallback(() => {
+    if (modelRef.current?.memoryTracker) {
+      setMemorySummary(modelRef.current.memoryTracker.getSummary());
+    }
+  }, []);
+
+  // Initialize the model instance
+  useEffect(() => {
+    modelRef.current = createLLM({
+      enableMemoryTracking,
+      maxMemorySnapshots,
+    });
+
+    // Reset ready state — the new instance has no model loaded yet.
+    // This prevents stale isReady=true after Fast Refresh (which
+    // preserves useState but re-runs useEffect).
+    setIsReady(false);
+
+    // Cleanup on unmount
+    return () => {
+      try {
+        modelRef.current?.close();
+      } catch (e) {
+        console.warn("Failed to close model", e);
+      }
+    };
+  }, [enableMemoryTracking, maxMemorySnapshots]);
+
+  const load = useCallback(async () => {
+    setIsReady(false);
+    setError(null);
+    setDownloadProgress(0);
+
+    try {
+      if (modelRef.current) {
+        // Delegate URL handling + download to the factory's loadModel,
+        // passing our progress setter as the callback (eliminates
+        // duplicate download logic that was previously in this hook).
+        await modelRef.current.loadModel(
+          pathOrUrl,
+          nativeConfig,
+          (progress) => {
+            setDownloadProgress(progress);
+          },
+        );
+        setIsReady(true);
+      }
+    } catch (e: any) {
+      setError(e.message || "Failed to load model");
+      console.error(e);
+    }
+  }, [pathOrUrl, nativeConfig]);
+
+  useEffect(() => {
+    if (autoLoad) {
+      load();
+    }
+  }, [autoLoad, load]);
+
+  const generate = useCallback(
+    async (prompt: string) => {
+      if (!modelRef.current || !isReady) {
+        throw new Error("Model not ready");
+      }
+
+      setIsGenerating(true);
+      try {
+        const response = await modelRef.current.execute(
+          [{ type: "text", text: prompt }],
+          undefined
+        );
+        refreshMemorySummary();
+        return response;
+      } catch (e: any) {
+        setError(e.message || "Generation failed");
+        throw e;
+      } finally {
+        setIsGenerating(false);
+      }
+    },
+    [isReady, refreshMemorySummary],
+  );
+
+  const reset = useCallback(() => {
+    if (modelRef.current) {
+      modelRef.current.resetConversation();
+    }
+  }, []);
+
+  const deleteModel = useCallback(
+    async (fileName?: string): Promise<void> => {
+      const resolvedName = fileName ?? extractFileName(pathOrUrl);
+      ModelRegistry.deleteFile(resolvedName);
+      setIsReady(false);
+      setDownloadProgress(0);
+    },
+    [pathOrUrl],
+  );
+
+  return {
+    model: modelRef.current,
+    isReady,
+    isGenerating,
+    downloadProgress,
+    error,
+    generate,
+    reset,
+    deleteModel,
+    load,
+    memoryTracker: modelRef.current?.memoryTracker ?? null,
+    memorySummary,
+  };
+}

package/src/index.ts

@@ -0,0 +1,214 @@
+import { NitroModules } from "react-native-nitro-modules";
+import { Platform } from "react-native";
+import type {
+  LiteRTLM,
+  LLMConfig,
+  Message,
+  Backend,
+  Role,
+  GenerationStats,
+  MemoryUsage,
+} from "./specs/LiteRTLM.nitro";
+
+export type {
+  LiteRTLM,
+  LLMConfig,
+  Message,
+  Backend,
+  Role,
+  GenerationStats,
+  MemoryUsage,
+  /** New in v0.5: pass to execute() instead of individual send methods */
+  MultimodalPart,
+  PartType,
+  /** Tool calling types */
+  ToolDefinition,
+  ToolCall,
+  ToolResponse,
+  ExecuteResult,
+} from "./specs/LiteRTLM.nitro";
+
+
+// Re-export memory tracking utilities (uses NitroModules.createNativeArrayBuffer v0.35+)
+export type {
+  MemorySnapshot,
+  MemoryTracker,
+  MemoryTrackerSummary,
+} from "./memoryTracker";
+export { createMemoryTracker, createNativeBuffer } from "./memoryTracker";
+
+export type { LiteRTLMInstance } from "./modelFactory";
+export { ModelRegistry } from "./modelRegistry";
+export type { ModelDownloadOptions } from "./modelRegistry";
+export * from "./hooks";
+
+/**
+ * Creates a new LiteRT-LM inference engine instance.
+ *
+ * @example
+ * ```typescript
+ * import { createLLM } from 'react-native-litert-lm';
+ *
+ * const llm = createLLM();
+ * await llm.loadModel('/path/to/gemma-3n-e2b.litertlm', {
+ *   backend: 'gpu',
+ *   temperature: 0.7,
+ *   maxContextTokens: 4096,
+ *   maxOutputTokens: 512
+ * });
+ *
+ * // ── Unified entry point (recommended) ─────────────────────────────────────
+ * // Blocking text
+ * const response = await llm.execute([{ type: 'text', text: 'Hello!' }]);
+ *
+ * // Streaming text
+ * await llm.execute(
+ *   [{ type: 'text', text: 'Write me a haiku' }],
+ *   (token, done) => { process.stdout.write(token); }
+ * );
+ *
+ * // Multimodal (image path — auto-scaled to 1024px on both platforms)
+ * const desc = await llm.execute([
+ *   { type: 'text', text: 'Describe this image' },
+ *   { type: 'image', path: '/path/to/photo.jpg' },
+ * ]);
+ *
+ * // ── Legacy methods (still fully supported) ────────────────────────────────
+ * const r = await llm.sendMessage('Hello');
+ * llm.sendMessageAsync('Stream this', (t, done) => console.log(t));
+ *
+ * llm.close();
+ * ```
+ */
+export { createLLM } from "./modelFactory";
+
+/**
+ * Pre-defined model identifiers for common models.
+ * Use with model download utilities or as reference.
+ */
+export const Models = {
+  /** Gemma 4 E2B Instruct (2B parameters, latest generation) */
+  GEMMA_4_E2B: "gemma-4-E2B-it-litert-lm",
+  /** Gemma 4 E4B Instruct (4B parameters, higher quality) */
+  GEMMA_4_E4B: "gemma-4-E4B-it-litert-lm",
+  /** Gemma 3n E2B (2B parameters, efficient) */
+  GEMMA_3N_E2B: "gemma-3n-E2B-it-litert-lm-preview",
+  /** Gemma 3n E4B (4B parameters, higher quality) */
+  GEMMA_3N_E4B: "gemma-3n-E4B-it-litert-lm-preview",
+  /** Gemma 3 1B (smallest Gemma) */
+  GEMMA_3_1B: "Gemma3-1B-IT_multi-prefill-seq_q4_ekv4096",
+  /** Phi-4 Mini Instruct */
+  PHI_4_MINI: "Phi-4-mini-instruct_multi-prefill-seq_q8_ekv4096",
+  /** Qwen 2.5 1.5B Instruct */
+  QWEN_2_5_1_5B: "Qwen2.5-1.5B-Instruct_multi-prefill-seq_q8_ekv4096",
+} as const;
+
+export type ModelId = (typeof Models)[keyof typeof Models];
+
+/**
+ * Get the recommended backend for the current platform.
+ * Returns 'cpu' as the safe default. GPU (Metal on iOS, GPU delegate on Android)
+ * is faster but may not be available on all devices or model configurations.
+ *
+ * @returns The recommended backend ('cpu')
+ *
+ * @example
+ * ```typescript
+ * const backend = getRecommendedBackend();
+ * llm.loadModel(path, { backend });
+ * ```
+ */
+export function getRecommendedBackend(): Backend {
+  // CPU is the safe default — always available, broadly compatible.
+  // GPU is faster but may fail on some models/devices.
+  return "cpu";
+}
+
+/**
+ * Check if a backend configuration is supported on the current platform.
+ * Returns a warning message if the configuration may have issues.
+ *
+ * @param backend The backend to check
+ * @returns Warning message if there may be issues, undefined if OK
+ *
+ * @example
+ * ```typescript
+ * const warning = checkBackendSupport('npu');
+ * if (warning) {
+ *   console.warn(warning);
+ * }
+ * ```
+ */
+export function checkBackendSupport(backend: Backend): string | undefined {
+  if (backend === "gpu") {
+    if (Platform.OS === "android") {
+      // GPU uses OpenCL on Android. Supported on many devices (Mali, Adreno, etc.)
+      // but may not be available on all. The engine will automatically fall back
+      // to CPU if GPU initialization fails.
+      return "GPU acceleration uses OpenCL. If unavailable on this device, the engine will automatically fall back to CPU.";
+    }
+    // iOS always supports GPU via Metal
+    return undefined;
+  }
+
+  if (backend === "npu") {
+    if (Platform.OS === "android") {
+      return "NPU backend requires compatible hardware (Qualcomm Hexagon, MediaTek APU, etc.). Will automatically fall back to CPU if unavailable.";
+    }
+    if (Platform.OS === "ios") {
+      return "NPU (Neural Engine) is not yet supported on iOS. Mapped to GPU (Metal) internally.";
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Check if multimodal features (image/audio) are supported on the current platform.
+ * Returns an error message if not supported, undefined if OK.
+ *
+ * Both iOS (v0.12.0 CLiteRTLM xcframework) and Android (LiteRT-LM SDK) ship the
+ * vision/audio executor ops, so there is no platform-level block. Whether a
+ * given call succeeds depends on the **loaded model**: only multimodal models
+ * (e.g. Gemma 3n) bundle the vision/audio executors. Pass `multimodal: true` to
+ * `loadModel` for such models, or rely on filename sniffing ("3n"/"gemma3").
+ *
+ * @returns Error message if multimodal is not supported, undefined if OK
+ *
+ * @example
+ * ```typescript
+ * const error = checkMultimodalSupport();
+ * if (error) {
+ *   console.warn(error);
+ *   // Fall back to text-only
+ * } else {
+ *   llm.sendMessageWithImage('Describe this', imagePath);
+ * }
+ * ```
+ */
+export function checkMultimodalSupport(): string | undefined {
+  // Supported on both platforms with a multimodal model loaded.
+  return undefined;
+}
+
+/**
+ * Download URL for the Gemma 3n E2B IT INT4 model (~1.3 GB).
+ * Public — hosted on litert.dev, no authentication required.
+ */
+export const GEMMA_3N_E2B_IT_INT4 =
+  "https://litert.dev/gemma-3n-E2B-it-int4.litertlm";
+
+/**
+ * Download URL for the Gemma 4 E2B IT model (2.58 GB).
+ * Public — no HuggingFace account required.
+ */
+export const GEMMA_4_E2B_IT =
+  "https://huggingface.co/litert-community/gemma-4-E2B-it-litert-lm/resolve/main/gemma-4-E2B-it.litertlm";
+
+/**
+ * Download URL for the Gemma 4 E4B IT model (3.65 GB).
+ * Higher quality than E2B but requires more device memory.
+ * Public — no HuggingFace account required.
+ */
+export const GEMMA_4_E4B_IT =
+  "https://huggingface.co/litert-community/gemma-4-E4B-it-litert-lm/resolve/main/gemma-4-E4B-it.litertlm";