@dr33m/react-native-litert-lm 0.5.0

package/scripts/postinstall.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * postinstall.js
+ *
+ * Downloads prebuilt LiteRT-LM iOS frameworks from this package's GitHub
+ * releases when consumers run `npm install react-native-litert-lm`.
+ *
+ * The framework is intentionally NOT shipped inside the npm tarball (it is
+ * ~40MB and irrelevant to Android-only consumers). The asset name, tag, and
+ * URL come from scripts/framework-source.js so they stay in lockstep with the
+ * release-time guardrail (scripts/check-framework-release.js).
+ *
+ * Skips download if:
+ *   - Not on macOS (iOS builds require macOS)
+ *   - Frameworks already exist
+ *   - SKIP_IOS_FRAMEWORK_DOWNLOAD=1 (e.g. Android-only / CI builds)
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const { ASSET_URL, FRAMEWORKS_DIR, FRAMEWORK_TAG } = require('./framework-source');
+
+/** ZIP local-file-header magic ("PK\x03\x04"). Guards against truncated downloads / HTML error pages. */
+const ZIP_MAGIC = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
+/** A valid framework zip is well over this; anything smaller is certainly an error page. */
+const MIN_VALID_BYTES = 1024 * 1024; // 1 MB
+
+function log(msg) {
+  console.log(`[react-native-litert-lm] ${msg}`);
+}
+
+function shouldSkip() {
+  // Skip if not macOS
+  if (process.platform !== 'darwin') {
+    log('Skipping iOS framework download (not macOS).');
+    return true;
+  }
+
+  // Skip if explicitly disabled
+  if (process.env.SKIP_IOS_FRAMEWORK_DOWNLOAD === '1') {
+    log('Skipping iOS framework download (SKIP_IOS_FRAMEWORK_DOWNLOAD=1).');
+    return true;
+  }
+
+  // Skip if frameworks already exist
+  if (fs.existsSync(FRAMEWORKS_DIR) && fs.readdirSync(FRAMEWORKS_DIR).length > 0) {
+    log('iOS frameworks already present, skipping download.');
+    return true;
+  }
+
+  return false;
+}
+
+function downloadFile(url, destPath, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    if (maxRedirects <= 0) {
+      return reject(new Error('Too many redirects'));
+    }
+
+    const protocol = url.startsWith('https') ? https : require('http');
+
+    protocol.get(url, { headers: { 'User-Agent': 'react-native-litert-lm' } }, (res) => {
+      // Follow redirects
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return downloadFile(res.headers.location, destPath, maxRedirects - 1)
+          .then(resolve)
+          .catch(reject);
+      }
+
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode} downloading ${url}`));
+      }
+
+      const file = fs.createWriteStream(destPath);
+      res.pipe(file);
+      file.on('finish', () => {
+        file.close(resolve);
+      });
+      file.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Verify the downloaded file is a non-trivial ZIP before we trust it.
+ * Catches GitHub HTML error pages and truncated downloads that would
+ * otherwise fail cryptically at `unzip` or, worse, link a corrupt framework.
+ */
+function assertValidZip(zipPath) {
+  const { size } = fs.statSync(zipPath);
+  if (size < MIN_VALID_BYTES) {
+    throw new Error(`downloaded asset is only ${size} bytes — expected a multi-MB framework zip (likely an error page or truncated download)`);
+  }
+
+  const header = Buffer.alloc(4);
+  const fd = fs.openSync(zipPath, 'r');
+  try {
+    fs.readSync(fd, header, 0, 4, 0);
+  } finally {
+    fs.closeSync(fd);
+  }
+  if (!header.equals(ZIP_MAGIC)) {
+    throw new Error('downloaded asset is not a valid ZIP (bad magic bytes)');
+  }
+}
+
+async function main() {
+  if (shouldSkip()) return;
+
+  log(`Downloading iOS frameworks (engine ${FRAMEWORK_TAG}) from: ${ASSET_URL}`);
+
+  const tmpZip = path.join(path.dirname(FRAMEWORKS_DIR), '.ios-frameworks-tmp.zip');
+
+  try {
+    await downloadFile(ASSET_URL, tmpZip);
+    assertValidZip(tmpZip);
+
+    // Extract
+    fs.mkdirSync(FRAMEWORKS_DIR, { recursive: true });
+    execSync(`unzip -o -q "${tmpZip}" -d "${FRAMEWORKS_DIR}"`, { stdio: 'inherit' });
+
+    // Cleanup
+    fs.unlinkSync(tmpZip);
+
+    log('iOS frameworks installed successfully.');
+  } catch (err) {
+    // Cleanup partial download
+    try { fs.unlinkSync(tmpZip); } catch {}
+
+    log(`Error: Could not download iOS frameworks: ${err.message}`);
+    log('iOS builds will not work until frameworks are available.');
+    log('Run: ./scripts/download-ios-frameworks.sh to download manually.');
+
+    // Fail fast on macOS so users discover the problem now, not at Xcode link time.
+    if (process.platform === 'darwin') {
+      log('Set SKIP_IOS_FRAMEWORK_DOWNLOAD=1 to suppress this error (e.g. Android-only builds).');
+      process.exit(1);
+    }
+  }
+}
+
+main();

package/src/__mocks__/react-native-nitro-modules.ts

@@ -0,0 +1,132 @@
+import type { MultimodalPart } from "../specs/LiteRTLM.nitro";
+
+function streamMockTokens(
+  parts: MultimodalPart[],
+  onToken: (token: string, done: boolean) => void,
+): void {
+  const hasImage = parts.some((p) => p.type === "image");
+  const hasAudio = parts.some((p) => p.type === "audio");
+  if (hasImage) {
+    onToken("Mock vision ", false);
+    onToken("token", true);
+  } else if (hasAudio) {
+    onToken("Mock audio ", false);
+    onToken("token", true);
+  } else {
+    onToken("Mock ", false);
+    onToken("token", true);
+  }
+}
+
+function mockExecuteResponse(parts: MultimodalPart[]): string {
+  const hasImage = parts.some((p) => p.type === "image");
+  const hasAudio = parts.some((p) => p.type === "audio");
+  return hasImage
+    ? "Mock vision token"
+    : hasAudio
+      ? "Mock audio token"
+      : "Mock token";
+}
+
+const mockExecute = jest.fn(
+  (parts: MultimodalPart[], onToken?: (token: string, done: boolean) => void): Promise<string> => {
+    if (onToken) {
+      streamMockTokens(parts, onToken);
+    }
+    return Promise.resolve(mockExecuteResponse(parts));
+  },
+);
+
+export const mockLiteRTLM = {
+  isReady: jest.fn(() => false),
+  loadModel: jest.fn().mockResolvedValue(undefined),
+  execute: mockExecute,
+  sendMessage: jest.fn((message: string) =>
+    mockExecute([{ type: "text", text: message }]),
+  ),
+  sendMessageWithImage: jest.fn((message: string, imagePath: string) =>
+    mockExecute([
+      { type: "text", text: message },
+      { type: "image", path: imagePath },
+    ]),
+  ),
+  downloadModel: jest.fn(async (url: string, fileName: string, onProgress?: (progress: number) => void) => {
+    onProgress?.(1.0);
+    return "/mock/path/model.litertlm";
+  }),
+  deleteModel: jest.fn().mockResolvedValue(undefined),
+  sendMessageWithAudio: jest.fn((message: string, audioPath: string) =>
+    mockExecute([
+      { type: "text", text: message },
+      { type: "audio", path: audioPath },
+    ]),
+  ),
+  sendMultimodalMessage: jest.fn((parts: MultimodalPart[]) => mockExecute(parts)),
+  sendMessageAsync: jest.fn((msg: string, onToken: (token: string, done: boolean) => void) =>
+    mockExecute([{ type: "text", text: msg }], onToken).then(() => {}),
+  ),
+  sendMessageWithImageAsync: jest.fn(
+    (msg: string, imagePath: string, onToken: (token: string, done: boolean) => void) =>
+      mockExecute(
+        [{ type: "text", text: msg }, { type: "image", path: imagePath }],
+        onToken,
+      ).then(() => {}),
+  ),
+  sendMessageWithAudioAsync: jest.fn(
+    (msg: string, audioPath: string, onToken: (token: string, done: boolean) => void) =>
+      mockExecute(
+        [{ type: "text", text: msg }, { type: "audio", path: audioPath }],
+        onToken,
+      ).then(() => {}),
+  ),
+  getHistory: jest.fn(() => []),
+  resetConversation: jest.fn(),
+  getStats: jest.fn(() => ({
+    promptTokens: 10,
+    completionTokens: 20,
+    totalTokens: 30,
+    timeToFirstToken: 5,
+    totalTime: 50,
+    tokensPerSecond: 400,
+  })),
+  countTokens: jest.fn(() => -1),
+  getMemoryUsage: jest.fn(() => ({
+    nativeHeapBytes: 1000000,
+    residentBytes: 2000000,
+    availableMemoryBytes: 4000000,
+    isLowMemory: false,
+  })),
+  close: jest.fn(),
+};
+
+export const mockModelStore = {
+  isCached: jest.fn((fileName: string) => false),
+  getFilePath: jest.fn((fileName: string) => `/mock/path/${fileName}`),
+  listCachedFiles: jest.fn(() => []),
+  deleteFile: jest.fn((fileName: string) => {
+    return mockLiteRTLM.deleteModel(fileName);
+  }),
+  downloadFile: jest.fn(
+    async (
+      url: string,
+      fileName: string,
+      headersJson: string,
+      onProgress: (progress: number) => void,
+    ) => mockLiteRTLM.downloadModel(url, fileName, onProgress),
+  ),
+};
+
+export const NitroModules = {
+  createHybridObject: jest.fn((name: string) => {
+    if (name === "LiteRTLM") {
+      return mockLiteRTLM;
+    }
+    if (name === "ModelStore") {
+      return mockModelStore;
+    }
+    throw new Error(`Mock not implemented for hybrid object: ${name}`);
+  }),
+  createNativeArrayBuffer: jest.fn((size: number) => {
+    return new ArrayBuffer(size);
+  }),
+};

package/src/__tests__/hooks.test.ts

@@ -0,0 +1,216 @@
+// Configure React act environment
+(global as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+import { useModel } from '../hooks';
+import { mockLiteRTLM } from '../__mocks__/react-native-nitro-modules';
+import TestRenderer from 'react-test-renderer';
+import React from 'react';
+
+// Mock react-native
+jest.mock('react-native', () => ({
+  Platform: {
+    OS: 'ios',
+    select: jest.fn((dict) => dict.ios),
+  },
+}));
+
+// Helper to render and test hooks using react-test-renderer
+function renderHook<P, R>(callback: (props: P) => R, initialProps?: P) {
+  let result = { current: null as unknown as R };
+  
+  const TestComponent = ({ props }: { props: P }) => {
+    result.current = callback(props);
+    return null;
+  };
+
+  let renderer: TestRenderer.ReactTestRenderer;
+  TestRenderer.act(() => {
+    renderer = TestRenderer.create(React.createElement(TestComponent, { props: initialProps as P }));
+  });
+
+  const rerender = (newProps: P) => {
+    TestRenderer.act(() => {
+      renderer.update(React.createElement(TestComponent, { props: newProps }));
+    });
+  };
+
+  const unmount = () => {
+    TestRenderer.act(() => {
+      renderer.unmount();
+    });
+  };
+
+  return { result, rerender, unmount };
+}
+
+describe('useModel React Hook Unit Tests', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should initialize with correct default state and call loadModel automatically when autoLoad is true', async () => {
+    let hookResult: any;
+    
+    await TestRenderer.act(async () => {
+      hookResult = renderHook(() => useModel('https://example.com/model.litertlm', { autoLoad: true }));
+    });
+
+    expect(hookResult.result.current.isReady).toBe(true);
+    expect(hookResult.result.current.isGenerating).toBe(false);
+    expect(hookResult.result.current.downloadProgress).toBe(1); // loadModel completed
+    expect(hookResult.result.current.error).toBeNull();
+    expect(mockLiteRTLM.loadModel).toHaveBeenCalled();
+  });
+
+  it('should not call loadModel automatically when autoLoad is false', async () => {
+    let hookResult: any;
+    
+    await TestRenderer.act(async () => {
+      hookResult = renderHook(() => useModel('https://example.com/model.litertlm', { autoLoad: false }));
+    });
+
+    expect(hookResult.result.current.isReady).toBe(false);
+    expect(mockLiteRTLM.loadModel).not.toHaveBeenCalled();
+
+    // Call load manually
+    await TestRenderer.act(async () => {
+      await hookResult.result.current.load();
+    });
+
+    expect(hookResult.result.current.isReady).toBe(true);
+    expect(mockLiteRTLM.loadModel).toHaveBeenCalled();
+  });
+
+  it('should handle model load failure gracefully', async () => {
+    mockLiteRTLM.loadModel.mockRejectedValueOnce(new Error("Model load failed"));
+    let hookResult: any;
+
+    await TestRenderer.act(async () => {
+      hookResult = renderHook(() => useModel('https://example.com/model.litertlm', { autoLoad: true }));
+    });
+
+    expect(hookResult.result.current.isReady).toBe(false);
+    expect(hookResult.result.current.error).toBe("Model load failed");
+  });
+
+  it('should generate text successfully and trigger memory summary update', async () => {
+    let hookResult: any;
+    
+    await TestRenderer.act(async () => {
+      hookResult = renderHook(() => useModel('https://example.com/model.litertlm', { 
+        autoLoad: true,
+        enableMemoryTracking: true 
+      }));
+    });
+
+    let response = "";
+    await TestRenderer.act(async () => {
+      response = await hookResult.result.current.generate("Test prompt");
+    });
+
+    expect(response).toBe("Mock token");
+    expect(mockLiteRTLM.execute).toHaveBeenCalledWith(
+      [{ type: "text", text: "Test prompt" }],
+      undefined,
+    );
+    expect(hookResult.result.current.memorySummary).toBeDefined();
+  });
+
+  it('should reset conversation correctly', async () => {
+    let hookResult: any;
+    
+    await TestRenderer.act(async () => {
+      hookResult = renderHook(() => useModel('https://example.com/model.litertlm', { autoLoad: true }));
+    });
+
+    hookResult.result.current.reset();
+    expect(mockLiteRTLM.resetConversation).toHaveBeenCalled();
+  });
+
+  it('should delete model file correctly', async () => {
+    let hookResult: any;
+    
+    await TestRenderer.act(async () => {
+      hookResult = renderHook(() => useModel('https://example.com/model.litertlm', { autoLoad: true }));
+    });
+
+    await TestRenderer.act(async () => {
+      await hookResult.result.current.deleteModel();
+    });
+
+    expect(mockLiteRTLM.deleteModel).toHaveBeenCalledWith('model.litertlm');
+    expect(hookResult.result.current.isReady).toBe(false);
+    expect(hookResult.result.current.downloadProgress).toBe(0);
+  });
+
+  it('should call close on unmount', async () => {
+    let hookResult: any;
+    
+    await TestRenderer.act(async () => {
+      hookResult = renderHook(() => useModel('https://example.com/model.litertlm', { autoLoad: false }));
+    });
+
+    hookResult.unmount();
+    expect(mockLiteRTLM.close).toHaveBeenCalled();
+  });
+
+  it('should pass maxContextTokens and maxOutputTokens through to loadModel', async () => {
+    let hookResult: any;
+
+    await TestRenderer.act(async () => {
+      hookResult = renderHook(() => useModel('https://example.com/model.litertlm', {
+        autoLoad: true,
+        maxContextTokens: 8192,
+        maxOutputTokens: 2048,
+      }));
+    });
+
+    expect(mockLiteRTLM.loadModel).toHaveBeenCalled();
+    const callArgs = mockLiteRTLM.loadModel.mock.calls[0];
+    const config = callArgs[1];
+    expect(config).toMatchObject({
+      maxContextTokens: 8192,
+      maxOutputTokens: 2048,
+    });
+  });
+
+  it('should pass legacy maxTokens through when new fields are not set', async () => {
+    let hookResult: any;
+
+    await TestRenderer.act(async () => {
+      hookResult = renderHook(() => useModel('https://example.com/model.litertlm', {
+        autoLoad: true,
+        maxTokens: 512,
+      }));
+    });
+
+    expect(mockLiteRTLM.loadModel).toHaveBeenCalled();
+    const callArgs = mockLiteRTLM.loadModel.mock.calls[0];
+    const config = callArgs[1];
+    expect(config).toMatchObject({ maxTokens: 512 });
+    expect(config.maxContextTokens).toBeUndefined();
+    expect(config.maxOutputTokens).toBeUndefined();
+  });
+
+  it('should pass both new fields alongside legacy maxTokens when all are set', async () => {
+    let hookResult: any;
+
+    await TestRenderer.act(async () => {
+      hookResult = renderHook(() => useModel('https://example.com/model.litertlm', {
+        autoLoad: true,
+        maxTokens: 512,
+        maxContextTokens: 4096,
+        maxOutputTokens: 1024,
+      }));
+    });
+
+    expect(mockLiteRTLM.loadModel).toHaveBeenCalled();
+    const callArgs = mockLiteRTLM.loadModel.mock.calls[0];
+    const config = callArgs[1];
+    expect(config).toMatchObject({
+      maxTokens: 512,
+      maxContextTokens: 4096,
+      maxOutputTokens: 1024,
+    });
+  });
+});

package/src/__tests__/inferenceRouting.test.ts

@@ -0,0 +1,36 @@
+import {
+  routeLegacyInference,
+  isLegacyInferenceMethod,
+  textPart,
+  imagePart,
+  audioPart,
+} from "../inferenceRouting";
+
+describe("inferenceRouting", () => {
+  it("routes sendMessage to a single text part", () => {
+    const route = routeLegacyInference("sendMessage", ["hello"]);
+    expect(route).toEqual({ parts: [textPart("hello")] });
+  });
+
+  it("routes sendMessageWithImageAsync with stream callback", () => {
+    const onToken = jest.fn();
+    const route = routeLegacyInference("sendMessageWithImageAsync", [
+      "describe",
+      "/img.jpg",
+      onToken,
+    ]);
+    expect(route).toEqual({
+      parts: [textPart("describe"), imagePart("/img.jpg")],
+      onToken,
+    });
+  });
+
+  it("returns null for unknown methods", () => {
+    expect(routeLegacyInference("downloadModel", ["url", "file"])).toBeNull();
+  });
+
+  it("isLegacyInferenceMethod narrows known methods", () => {
+    expect(isLegacyInferenceMethod("sendMessage")).toBe(true);
+    expect(isLegacyInferenceMethod("close")).toBe(false);
+  });
+});

package/src/__tests__/memoryTracker.test.ts

@@ -0,0 +1,87 @@
+import { createMemoryTracker, createNativeBuffer } from '../memoryTracker';
+import { NitroModules } from 'react-native-nitro-modules';
+
+describe('MemoryTracker Unit Tests', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should allocate correct native-backed ArrayBuffer size on initialization', () => {
+    const tracker = createMemoryTracker(10);
+    expect(NitroModules.createNativeArrayBuffer).toHaveBeenCalledWith(10 * 4 * 8); // 10 snapshots * 4 fields * 8 bytes/Float64
+    expect(tracker.getCapacity()).toBe(10);
+    expect(tracker.getSnapshotCount()).toBe(0);
+  });
+
+  it('should record snapshots correctly and retrieve them', () => {
+    const tracker = createMemoryTracker(5);
+    const snapshot1 = {
+      timestamp: 1000,
+      nativeHeapBytes: 100,
+      residentBytes: 200,
+      availableMemoryBytes: 500,
+    };
+    
+    expect(tracker.record(snapshot1)).toBe(true);
+    expect(tracker.getSnapshotCount()).toBe(1);
+    expect(tracker.getLatestSnapshot()).toEqual(snapshot1);
+    
+    const snapshots = tracker.getSnapshots();
+    expect(snapshots).toHaveLength(1);
+    expect(snapshots[0]).toEqual(snapshot1);
+  });
+
+  it('should reject new snapshots and return false when capacity is reached', () => {
+    const tracker = createMemoryTracker(2);
+    
+    expect(tracker.record({ timestamp: 1, nativeHeapBytes: 10, residentBytes: 20, availableMemoryBytes: 50 })).toBe(true);
+    expect(tracker.record({ timestamp: 2, nativeHeapBytes: 20, residentBytes: 30, availableMemoryBytes: 40 })).toBe(true);
+    expect(tracker.record({ timestamp: 3, nativeHeapBytes: 30, residentBytes: 40, availableMemoryBytes: 30 })).toBe(false);
+    
+    expect(tracker.getSnapshotCount()).toBe(2);
+  });
+
+  it('should calculate correct peak resident memory size', () => {
+    const tracker = createMemoryTracker(5);
+    tracker.record({ timestamp: 1, nativeHeapBytes: 100, residentBytes: 150, availableMemoryBytes: 1000 });
+    tracker.record({ timestamp: 2, nativeHeapBytes: 120, residentBytes: 300, availableMemoryBytes: 1000 });
+    tracker.record({ timestamp: 3, nativeHeapBytes: 110, residentBytes: 200, availableMemoryBytes: 1000 });
+
+    expect(tracker.getPeakMemory()).toBe(300);
+  });
+
+  it('should calculate accurate memory summary statistics', () => {
+    const tracker = createMemoryTracker(5);
+    tracker.record({ timestamp: 1, nativeHeapBytes: 50, residentBytes: 100, availableMemoryBytes: 1000 });
+    tracker.record({ timestamp: 2, nativeHeapBytes: 150, residentBytes: 300, availableMemoryBytes: 800 });
+    tracker.record({ timestamp: 3, nativeHeapBytes: 100, residentBytes: 200, availableMemoryBytes: 900 });
+
+    const summary = tracker.getSummary();
+    expect(summary.snapshotCount).toBe(3);
+    expect(summary.peakResidentBytes).toBe(300);
+    expect(summary.averageResidentBytes).toBe(200); // (100 + 300 + 200) / 3
+    expect(summary.currentResidentBytes).toBe(200);
+    expect(summary.peakNativeHeapBytes).toBe(150);
+    expect(summary.currentNativeHeapBytes).toBe(100);
+    expect(summary.residentDeltaBytes).toBe(100); // currentRss(200) - firstRss(100)
+    expect(summary.trackerBufferSizeBytes).toBe(5 * 4 * 8);
+  });
+
+  it('should preserve buffer but reset internal state when reset() is called', () => {
+    const tracker = createMemoryTracker(5);
+    tracker.record({ timestamp: 1, nativeHeapBytes: 50, residentBytes: 100, availableMemoryBytes: 1000 });
+    
+    expect(tracker.getSnapshotCount()).toBe(1);
+    tracker.reset();
+    expect(tracker.getSnapshotCount()).toBe(0);
+    expect(tracker.getLatestSnapshot()).toBeUndefined();
+    expect(tracker.getSnapshots()).toEqual([]);
+  });
+
+  it('should allow standalone native ArrayBuffer allocation via createNativeBuffer', () => {
+    const size = 128;
+    const buffer = createNativeBuffer(size);
+    expect(NitroModules.createNativeArrayBuffer).toHaveBeenCalledWith(size);
+    expect(buffer.byteLength).toBe(size);
+  });
+});