react-native-litert-lm 0.2.1 → 0.3.0

package/lib/hooks.d.ts

@@ -1,16 +1,46 @@
-import { LiteRTLM, LLMConfig } from "./index";
+import { LLMConfig } from "./index";
+import type { LiteRTLMInstance } from "./modelFactory";
+import type { MemoryTracker, MemoryTrackerSummary } from "./memoryTracker";
 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: LiteRTLM | null;
+    model: LiteRTLMInstance | null;
     isReady: boolean;
     isGenerating: boolean;
     downloadProgress: number;
     error: string | null;
     generate: (prompt: string) => Promise<string>;
     reset: () => void;
-    deleteModel: (fileName: string) => Promise<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 declare function useModel(pathOrUrl: string, config?: UseModelConfig): UseModelResult;

package/lib/hooks.js

@@ -3,21 +3,56 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useModel = useModel;
 const react_1 = require("react");
 const modelFactory_1 = require("./modelFactory");
+/**
+ * Extract a filename from a URL or file path.
+ */
+function extractFileName(pathOrUrl) {
+    return pathOrUrl.split("/").pop() || "model.bin";
+}
 function useModel(pathOrUrl, config) {
     const modelRef = (0, react_1.useRef)(null);
     const [isReady, setIsReady] = (0, react_1.useState)(false);
     const [isGenerating, setIsGenerating] = (0, react_1.useState)(false);
     const [downloadProgress, setDownloadProgress] = (0, react_1.useState)(0);
     const [error, setError] = (0, react_1.useState)(null);
-    // Extract autoLoad (default true)
+    const [memorySummary, setMemorySummary] = (0, react_1.useState)(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 temperature = config?.temperature;
+    const topK = config?.topK;
+    const topP = config?.topP;
+    // Build a stable config object from the destructured primitives
+    const nativeConfig = (0, react_1.useMemo)(() => ({
+        ...(backend !== undefined && { backend }),
+        ...(systemPrompt !== undefined && { systemPrompt }),
+        ...(maxTokens !== undefined && { maxTokens }),
+        ...(temperature !== undefined && { temperature }),
+        ...(topK !== undefined && { topK }),
+        ...(topP !== undefined && { topP }),
+    }), [backend, systemPrompt, maxTokens, temperature, topK, topP]);
+    /**
+     * Refresh memory summary from the tracker's native buffer.
+     */
+    const refreshMemorySummary = (0, react_1.useCallback)(() => {
+        if (modelRef.current?.memoryTracker) {
+            setMemorySummary(modelRef.current.memoryTracker.getSummary());
+        }
+    }, []);
     // Initialize the model instance
     (0, react_1.useEffect)(() => {
-        modelRef.current = (0, modelFactory_1.createLLM)();
-        let isMounted = true;
+        modelRef.current = (0, modelFactory_1.createLLM)({
+            enableMemoryTracking,
+            maxMemorySnapshots,
+        });
         // Cleanup on unmount
         return () => {
-            isMounted = false;
             try {
                 modelRef.current?.close();
             }
@@ -25,27 +60,19 @@ function useModel(pathOrUrl, config) {
                 console.warn("Failed to close model", e);
             }
         };
-    }, []);
+    }, [enableMemoryTracking, maxMemorySnapshots]);
     const load = (0, react_1.useCallback)(async () => {
         setIsReady(false);
         setError(null);
         setDownloadProgress(0);
         try {
-            let modelPath = pathOrUrl;
-            // Handle URL download manually to capture progress
-            if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) {
-                const fileName = pathOrUrl.split("/").pop() || "model.bin";
-                if (modelRef.current) {
-                    modelPath = await modelRef.current.downloadModel(pathOrUrl, fileName, (progress) => {
-                        setDownloadProgress(progress);
-                    });
-                }
-            }
             if (modelRef.current) {
-                // Create a clean config object for native loadModel (excluding autoLoad)
-                const nativeConfig = { ...config };
-                delete nativeConfig.autoLoad;
-                await modelRef.current.loadModel(modelPath, nativeConfig);
+                // 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);
             }
         }
@@ -53,7 +80,7 @@ function useModel(pathOrUrl, config) {
             setError(e.message || "Failed to load model");
             console.error(e);
         }
-    }, [pathOrUrl, config]);
+    }, [pathOrUrl, nativeConfig]);
     (0, react_1.useEffect)(() => {
         if (autoLoad) {
             load();
@@ -71,6 +98,7 @@ function useModel(pathOrUrl, config) {
                     modelRef.current?.sendMessageAsync(prompt, (token, done) => {
                         fullResponse += token;
                         if (done) {
+                            refreshMemorySummary();
                             resolve(fullResponse);
                         }
                     });
@@ -87,7 +115,7 @@ function useModel(pathOrUrl, config) {
         finally {
             setIsGenerating(false);
         }
-    }, [isReady]);
+    }, [isReady, refreshMemorySummary]);
     const reset = (0, react_1.useCallback)(() => {
         if (modelRef.current) {
             modelRef.current.resetConversation();
@@ -95,11 +123,12 @@ function useModel(pathOrUrl, config) {
     }, []);
     const deleteModel = (0, react_1.useCallback)(async (fileName) => {
         if (modelRef.current) {
-            await modelRef.current.deleteModel(fileName);
+            const resolvedName = fileName ?? extractFileName(pathOrUrl);
+            await modelRef.current.deleteModel(resolvedName);
             setIsReady(false);
             setDownloadProgress(0);
         }
-    }, []);
+    }, [pathOrUrl]);
     return {
         model: modelRef.current,
         isReady,
@@ -110,5 +139,7 @@ function useModel(pathOrUrl, config) {
         reset,
         deleteModel,
         load,
+        memoryTracker: modelRef.current?.memoryTracker ?? null,
+        memorySummary,
     };
 }

package/lib/index.d.ts

@@ -1,7 +1,10 @@
 import type { Backend } from "./specs/LiteRTLM.nitro";
-export type { LiteRTLM, LLMConfig, Message, Backend, Role, GenerationStats, } from "./specs/LiteRTLM.nitro";
+export type { LiteRTLM, LLMConfig, Message, Backend, Role, GenerationStats, MemoryUsage, } from "./specs/LiteRTLM.nitro";
 export type { ChatMessage } from "./templates";
 export { applyGemmaTemplate, applyPhiTemplate, applyLlamaTemplate, } from "./templates";
+export type { MemorySnapshot, MemoryTracker, MemoryTrackerSummary, } from "./memoryTracker";
+export { createMemoryTracker, createNativeBuffer } from "./memoryTracker";
+export type { LiteRTLMInstance } from "./modelFactory";
 export * from "./hooks";
 /**
  * Creates a new LiteRT-LM inference engine instance.

package/lib/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GEMMA_3N_E2B_IT_INT4 = exports.Models = exports.createLLM = exports.applyLlamaTemplate = exports.applyPhiTemplate = exports.applyGemmaTemplate = void 0;
+exports.GEMMA_3N_E2B_IT_INT4 = exports.Models = exports.createLLM = exports.createNativeBuffer = exports.createMemoryTracker = exports.applyLlamaTemplate = exports.applyPhiTemplate = exports.applyGemmaTemplate = void 0;
 exports.getRecommendedBackend = getRecommendedBackend;
 exports.checkBackendSupport = checkBackendSupport;
 exports.checkMultimodalSupport = checkMultimodalSupport;
@@ -23,6 +23,9 @@ var templates_1 = require("./templates");
 Object.defineProperty(exports, "applyGemmaTemplate", { enumerable: true, get: function () { return templates_1.applyGemmaTemplate; } });
 Object.defineProperty(exports, "applyPhiTemplate", { enumerable: true, get: function () { return templates_1.applyPhiTemplate; } });
 Object.defineProperty(exports, "applyLlamaTemplate", { enumerable: true, get: function () { return templates_1.applyLlamaTemplate; } });
+var memoryTracker_1 = require("./memoryTracker");
+Object.defineProperty(exports, "createMemoryTracker", { enumerable: true, get: function () { return memoryTracker_1.createMemoryTracker; } });
+Object.defineProperty(exports, "createNativeBuffer", { enumerable: true, get: function () { return memoryTracker_1.createNativeBuffer; } });
 __exportStar(require("./hooks"), exports);
 /**
  * Creates a new LiteRT-LM inference engine instance.
@@ -113,12 +116,9 @@ function checkBackendSupport(backend) {
             return "NPU backend requires compatible hardware (Qualcomm Hexagon, MediaTek APU, etc.). Will fall back to GPU if unavailable.";
         }
         if (react_native_1.Platform.OS === "ios") {
-            return "NPU/CoreML is not yet supported on iOS. LiteRT-LM iOS support is pending.";
+            return "NPU (Neural Engine) is not yet supported on iOS. Use 'gpu' (Metal) or 'cpu' instead.";
         }
     }
-    if (react_native_1.Platform.OS === "ios" && backend !== "cpu") {
-        return "LiteRT-LM iOS is not yet released. Only CPU backend may work via fallback.";
-    }
     return undefined;
 }
 /**
@@ -140,7 +140,7 @@ function checkBackendSupport(backend) {
  */
 function checkMultimodalSupport() {
     if (react_native_1.Platform.OS === "ios") {
-        return "Multimodal (image/audio) is not yet supported on iOS. LiteRT-LM iOS SDK is pending.";
+        return "Multimodal (image/audio) is experimental on iOS. Vision and audio executors may not be available in the current build.";
     }
     return undefined;
 }

package/lib/memoryTracker.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Memory tracking utilities for LiteRT-LM using real native memory metrics.
+ *
+ * Records real memory usage from OS-level APIs via `getMemoryUsage()`,
+ * and stores snapshots in a native-backed ArrayBuffer allocated via
+ * `NitroModules.createNativeArrayBuffer()` (v0.35+) for zero-copy interop.
+ *
+ * @example
+ * ```typescript
+ * import { createMemoryTracker } from 'react-native-litert-lm';
+ *
+ * const tracker = createMemoryTracker(100);
+ *
+ * // Record a real snapshot (typically called internally after inference)
+ * tracker.record({
+ *   timestamp: Date.now(),
+ *   nativeHeapBytes: usage.nativeHeapBytes,
+ *   residentBytes: usage.residentBytes,
+ *   availableMemoryBytes: usage.availableMemoryBytes,
+ * });
+ *
+ * console.log(`Peak RSS: ${tracker.getPeakMemory()} bytes`);
+ * ```
+ */
+/**
+ * A single memory usage snapshot with real data from OS APIs.
+ */
+export interface MemorySnapshot {
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Native heap allocated bytes (Debug.getNativeHeapAllocatedSize on Android, task_info on iOS) */
+    nativeHeapBytes: number;
+    /** Process resident set size (RSS) in bytes */
+    residentBytes: number;
+    /** Available system memory in bytes */
+    availableMemoryBytes: number;
+}
+/**
+ * Memory tracker that stores snapshots in a native-backed ArrayBuffer.
+ *
+ * Uses `NitroModules.createNativeArrayBuffer()` to allocate the backing
+ * buffer in native (C++) memory, ensuring zero-copy interop with native
+ * methods and keeping memory tracking data off the JS heap.
+ */
+export interface MemoryTracker {
+    /**
+     * Record a new memory snapshot.
+     * @param snapshot The memory usage data to record
+     * @returns true if recorded, false if buffer is full
+     */
+    record(snapshot: MemorySnapshot): boolean;
+    /**
+     * Get all recorded snapshots as structured objects.
+     */
+    getSnapshots(): MemorySnapshot[];
+    /**
+     * Get the number of recorded snapshots.
+     */
+    getSnapshotCount(): number;
+    /**
+     * Get the maximum number of snapshots this tracker can hold.
+     */
+    getCapacity(): number;
+    /**
+     * Get the peak resident set size across all snapshots.
+     */
+    getPeakMemory(): number;
+    /**
+     * Get the latest memory snapshot, or undefined if none recorded.
+     */
+    getLatestSnapshot(): MemorySnapshot | undefined;
+    /**
+     * Get the underlying native ArrayBuffer.
+     * This buffer is allocated via `NitroModules.createNativeArrayBuffer()`
+     * and lives in native memory, enabling zero-copy transfer to native methods.
+     */
+    getNativeBuffer(): ArrayBuffer;
+    /**
+     * Get the Float64Array view over the native buffer.
+     */
+    getView(): Float64Array;
+    /**
+     * Reset the tracker, clearing all recorded snapshots.
+     * The native buffer is preserved (not reallocated).
+     */
+    reset(): void;
+    /**
+     * Get a summary of memory usage statistics.
+     */
+    getSummary(): MemoryTrackerSummary;
+}
+/**
+ * Summary statistics from the memory tracker.
+ */
+export interface MemoryTrackerSummary {
+    /** Number of snapshots recorded */
+    snapshotCount: number;
+    /** Peak resident set size in bytes */
+    peakResidentBytes: number;
+    /** Average resident set size in bytes */
+    averageResidentBytes: number;
+    /** Latest resident set size in bytes */
+    currentResidentBytes: number;
+    /** Peak native heap allocated in bytes */
+    peakNativeHeapBytes: number;
+    /** Latest native heap allocated in bytes */
+    currentNativeHeapBytes: number;
+    /** RSS delta from first to last snapshot in bytes */
+    residentDeltaBytes: number;
+    /** Size of the native tracking buffer itself in bytes */
+    trackerBufferSizeBytes: number;
+}
+/**
+ * Create a new memory tracker backed by a native ArrayBuffer.
+ *
+ * @param maxSnapshots Maximum number of snapshots to store (default: 256)
+ * @returns A MemoryTracker instance
+ */
+export declare function createMemoryTracker(maxSnapshots?: number): MemoryTracker;
+/**
+ * Create a native ArrayBuffer for efficient data transfer.
+ *
+ * A convenience wrapper around `NitroModules.createNativeArrayBuffer()`.
+ *
+ * @param size Size in bytes
+ * @returns A native-backed ArrayBuffer
+ */
+export declare function createNativeBuffer(size: number): ArrayBuffer;

package/lib/memoryTracker.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * Memory tracking utilities for LiteRT-LM using real native memory metrics.
+ *
+ * Records real memory usage from OS-level APIs via `getMemoryUsage()`,
+ * and stores snapshots in a native-backed ArrayBuffer allocated via
+ * `NitroModules.createNativeArrayBuffer()` (v0.35+) for zero-copy interop.
+ *
+ * @example
+ * ```typescript
+ * import { createMemoryTracker } from 'react-native-litert-lm';
+ *
+ * const tracker = createMemoryTracker(100);
+ *
+ * // Record a real snapshot (typically called internally after inference)
+ * tracker.record({
+ *   timestamp: Date.now(),
+ *   nativeHeapBytes: usage.nativeHeapBytes,
+ *   residentBytes: usage.residentBytes,
+ *   availableMemoryBytes: usage.availableMemoryBytes,
+ * });
+ *
+ * console.log(`Peak RSS: ${tracker.getPeakMemory()} bytes`);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMemoryTracker = createMemoryTracker;
+exports.createNativeBuffer = createNativeBuffer;
+const react_native_nitro_modules_1 = require("react-native-nitro-modules");
+/** Number of Float64 fields per snapshot */
+const FIELDS_PER_SNAPSHOT = 4;
+/** Bytes per Float64 value */
+const BYTES_PER_FIELD = Float64Array.BYTES_PER_ELEMENT; // 8
+/**
+ * Create a new memory tracker backed by a native ArrayBuffer.
+ *
+ * @param maxSnapshots Maximum number of snapshots to store (default: 256)
+ * @returns A MemoryTracker instance
+ */
+function createMemoryTracker(maxSnapshots = 256) {
+    const bufferSize = maxSnapshots * FIELDS_PER_SNAPSHOT * BYTES_PER_FIELD;
+    // Use NitroModules.createNativeArrayBuffer for native-backed allocation.
+    const nativeBuffer = react_native_nitro_modules_1.NitroModules.createNativeArrayBuffer(bufferSize);
+    const view = new Float64Array(nativeBuffer);
+    let currentIndex = 0;
+    return {
+        record(snapshot) {
+            if (currentIndex >= maxSnapshots) {
+                return false;
+            }
+            const offset = currentIndex * FIELDS_PER_SNAPSHOT;
+            view[offset] = snapshot.timestamp;
+            view[offset + 1] = snapshot.nativeHeapBytes;
+            view[offset + 2] = snapshot.residentBytes;
+            view[offset + 3] = snapshot.availableMemoryBytes;
+            currentIndex++;
+            return true;
+        },
+        getSnapshots() {
+            const snapshots = [];
+            for (let i = 0; i < currentIndex; i++) {
+                const offset = i * FIELDS_PER_SNAPSHOT;
+                snapshots.push({
+                    timestamp: view[offset],
+                    nativeHeapBytes: view[offset + 1],
+                    residentBytes: view[offset + 2],
+                    availableMemoryBytes: view[offset + 3],
+                });
+            }
+            return snapshots;
+        },
+        getSnapshotCount() {
+            return currentIndex;
+        },
+        getCapacity() {
+            return maxSnapshots;
+        },
+        getPeakMemory() {
+            let peak = 0;
+            for (let i = 0; i < currentIndex; i++) {
+                const rss = view[i * FIELDS_PER_SNAPSHOT + 2];
+                if (rss > peak) {
+                    peak = rss;
+                }
+            }
+            return peak;
+        },
+        getLatestSnapshot() {
+            if (currentIndex === 0)
+                return undefined;
+            const offset = (currentIndex - 1) * FIELDS_PER_SNAPSHOT;
+            return {
+                timestamp: view[offset],
+                nativeHeapBytes: view[offset + 1],
+                residentBytes: view[offset + 2],
+                availableMemoryBytes: view[offset + 3],
+            };
+        },
+        getNativeBuffer() {
+            return nativeBuffer;
+        },
+        getView() {
+            return view;
+        },
+        reset() {
+            view.fill(0);
+            currentIndex = 0;
+        },
+        getSummary() {
+            let peakRss = 0;
+            let peakHeap = 0;
+            let sumRss = 0;
+            let firstRss = 0;
+            let lastRss = 0;
+            let lastHeap = 0;
+            for (let i = 0; i < currentIndex; i++) {
+                const offset = i * FIELDS_PER_SNAPSHOT;
+                const heap = view[offset + 1];
+                const rss = view[offset + 2];
+                if (rss > peakRss)
+                    peakRss = rss;
+                if (heap > peakHeap)
+                    peakHeap = heap;
+                sumRss += rss;
+                if (i === 0)
+                    firstRss = rss;
+                if (i === currentIndex - 1) {
+                    lastRss = rss;
+                    lastHeap = heap;
+                }
+            }
+            return {
+                snapshotCount: currentIndex,
+                peakResidentBytes: peakRss,
+                averageResidentBytes: currentIndex > 0 ? sumRss / currentIndex : 0,
+                currentResidentBytes: lastRss,
+                peakNativeHeapBytes: peakHeap,
+                currentNativeHeapBytes: lastHeap,
+                residentDeltaBytes: lastRss - firstRss,
+                trackerBufferSizeBytes: bufferSize,
+            };
+        },
+    };
+}
+/**
+ * Create a native ArrayBuffer for efficient data transfer.
+ *
+ * A convenience wrapper around `NitroModules.createNativeArrayBuffer()`.
+ *
+ * @param size Size in bytes
+ * @returns A native-backed ArrayBuffer
+ */
+function createNativeBuffer(size) {
+    return react_native_nitro_modules_1.NitroModules.createNativeArrayBuffer(size);
+}

package/lib/modelFactory.d.ts

@@ -1,5 +1,24 @@
-import { LiteRTLM } from "./specs/LiteRTLM.nitro";
+import { LiteRTLM, LLMConfig } from "./specs/LiteRTLM.nitro";
+import { MemoryTracker } from "./memoryTracker";
+/**
+ * Extended LiteRT-LM instance with optional memory tracking and
+ * augmented loadModel that accepts a download progress callback.
+ */
+export type LiteRTLMInstance = Omit<LiteRTLM, "loadModel"> & {
+    memoryTracker?: MemoryTracker;
+    loadModel: (pathOrUrl: string, config?: LLMConfig, onDownloadProgress?: (progress: number) => void) => Promise<void>;
+};
 /**
  * Creates a new LiteRT-LM inference engine instance.
+ *
+ * Optionally creates a native-backed memory tracker using
+ * `NitroModules.createNativeArrayBuffer()` (v0.35+) for efficient
+ * zero-copy memory usage tracking.
+ *
+ * @param options.enableMemoryTracking Enable automatic memory tracking (default: false)
+ * @param options.maxMemorySnapshots Maximum number of memory snapshots to store (default: 256)
  */
-export declare function createLLM(): LiteRTLM;
+export declare function createLLM(options?: {
+    enableMemoryTracking?: boolean;
+    maxMemorySnapshots?: number;
+}): LiteRTLMInstance;

package/lib/modelFactory.js

@@ -2,17 +2,54 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createLLM = createLLM;
 const react_native_nitro_modules_1 = require("react-native-nitro-modules");
+const memoryTracker_1 = require("./memoryTracker");
 /**
  * Creates a new LiteRT-LM inference engine instance.
+ *
+ * Optionally creates a native-backed memory tracker using
+ * `NitroModules.createNativeArrayBuffer()` (v0.35+) for efficient
+ * zero-copy memory usage tracking.
+ *
+ * @param options.enableMemoryTracking Enable automatic memory tracking (default: false)
+ * @param options.maxMemorySnapshots Maximum number of memory snapshots to store (default: 256)
  */
-function createLLM() {
+function createLLM(options) {
     const native = react_native_nitro_modules_1.NitroModules.createHybridObject("LiteRTLM");
+    const enableTracking = options?.enableMemoryTracking ?? false;
+    const tracker = enableTracking
+        ? (0, memoryTracker_1.createMemoryTracker)(options?.maxMemorySnapshots ?? 256)
+        : undefined;
+    /**
+     * Record a real memory snapshot using OS-level APIs via getMemoryUsage().
+     */
+    const recordMemorySnapshot = () => {
+        if (!tracker)
+            return;
+        try {
+            const usage = native.getMemoryUsage();
+            tracker.record({
+                timestamp: Date.now(),
+                nativeHeapBytes: usage.nativeHeapBytes,
+                residentBytes: usage.residentBytes,
+                availableMemoryBytes: usage.availableMemoryBytes,
+            });
+        }
+        catch {
+            // Ignore errors during memory tracking - it's non-critical
+        }
+    };
     return {
         ...native,
-        loadModel: async (pathOrUrl, config) => {
+        memoryTracker: tracker,
+        loadModel: async (pathOrUrl, config, onDownloadProgress) => {
             let modelPath = pathOrUrl;
-            // Check if it's a URL
+            // Check if it's a URL — enforce HTTPS for model downloads
             if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) {
+                if (pathOrUrl.startsWith("http://")) {
+                    throw new Error("Insecure HTTP URLs are not allowed for model downloads. " +
+                        "Use HTTPS instead: " +
+                        pathOrUrl.replace("http://", "https://"));
+                }
                 // Extract filename from URL
                 const fileName = pathOrUrl.split("/").pop();
                 if (!fileName) {
@@ -20,21 +57,51 @@ function createLLM() {
                 }
                 console.log(`Checking model at ${pathOrUrl}...`);
                 modelPath = await native.downloadModel(pathOrUrl, fileName, (progress) => {
-                    console.log(`Download progress: ${progress}`);
+                    onDownloadProgress?.(progress);
                 });
                 console.log(`Model downloaded to: ${modelPath}`);
             }
-            return native.loadModel(modelPath, config);
+            const result = await native.loadModel(modelPath, config);
+            // Record initial memory snapshot after model load
+            if (tracker) {
+                tracker.reset();
+                recordMemorySnapshot();
+            }
+            return result;
+        },
+        sendMessage: async (...args) => {
+            const result = await native.sendMessage(...args);
+            recordMemorySnapshot();
+            return result;
+        },
+        sendMessageAsync: (...args) => {
+            const [message, onToken] = args;
+            native.sendMessageAsync(message, (token, done) => {
+                onToken(token, done);
+                if (done) {
+                    recordMemorySnapshot();
+                }
+            });
+        },
+        sendMessageWithImage: async (...args) => {
+            const result = await native.sendMessageWithImage(...args);
+            recordMemorySnapshot();
+            return result;
+        },
+        sendMessageWithAudio: async (...args) => {
+            const result = await native.sendMessageWithAudio(...args);
+            recordMemorySnapshot();
+            return result;
         },
-        // Bind valid methods to native instance
-        sendMessage: native.sendMessage.bind(native),
-        sendMessageAsync: native.sendMessageAsync.bind(native),
-        sendMessageWithImage: native.sendMessageWithImage.bind(native),
-        sendMessageWithAudio: native.sendMessageWithAudio.bind(native),
         getHistory: native.getHistory.bind(native),
-        resetConversation: native.resetConversation.bind(native),
+        resetConversation: () => {
+            native.resetConversation();
+            // KV cache is cleared on reset, record the drop
+            recordMemorySnapshot();
+        },
         isReady: native.isReady.bind(native),
         getStats: native.getStats.bind(native),
+        getMemoryUsage: native.getMemoryUsage.bind(native),
         close: native.close.bind(native),
         downloadModel: native.downloadModel.bind(native),
         deleteModel: native.deleteModel.bind(native),