@runanywhere/web 0.1.0-beta.1

package/dist/Infrastructure/OPFSStorage.js

@@ -0,0 +1,330 @@
+/**
+ * RunAnywhere Web SDK - OPFS (Origin Private File System) Storage
+ *
+ * Persistent model storage using the browser's Origin Private File System.
+ * OPFS provides a sandboxed, high-performance file system for large model files
+ * that persists across page reloads (unlike Emscripten MEMFS).
+ *
+ * Supports nested paths: keys containing `/` are treated as subdirectory paths.
+ *   e.g. `saveModel('org/model/file.gguf', data)` creates `models/org/model/file.gguf`
+ *
+ * Fallback: If OPFS is not available, models stay in MEMFS (volatile).
+ *
+ * Usage:
+ *   import { OPFSStorage } from '@runanywhere/web';
+ *
+ *   const storage = new OPFSStorage();
+ *   await storage.saveModel('whisper-base', modelArrayBuffer);
+ *   await storage.saveModel('org/model/file.gguf', modelArrayBuffer);
+ *   const data = await storage.loadModel('whisper-base');
+ *   const models = await storage.listModels();
+ */
+import { SDKLogger } from '../Foundation/SDKLogger';
+const logger = new SDKLogger('OPFSStorage');
+/** OPFS root directory name for model storage. */
+const MODELS_DIR = 'models';
+/**
+ * OPFSStorage - Persistent model file storage using Origin Private File System.
+ *
+ * Keys can be flat (`whisper-base`) or nested (`org/model/file.gguf`).
+ * Nested keys are stored in the corresponding subdirectory hierarchy under the
+ * `models/` OPFS root.
+ */
+export class OPFSStorage {
+    rootDir = null;
+    modelsDir = null;
+    _isAvailable = null;
+    /**
+     * Check if OPFS is available in this browser.
+     */
+    static get isSupported() {
+        return typeof navigator !== 'undefined' &&
+            'storage' in navigator &&
+            'getDirectory' in (navigator.storage || {});
+    }
+    /**
+     * Initialize OPFS storage. Must be called before other methods.
+     *
+     * @returns true if OPFS was initialized, false if not available
+     */
+    async initialize() {
+        if (this._isAvailable !== null)
+            return this._isAvailable;
+        if (!OPFSStorage.isSupported) {
+            logger.warning('OPFS not available in this browser. Models will use volatile MEMFS.');
+            this._isAvailable = false;
+            return false;
+        }
+        try {
+            this.rootDir = await navigator.storage.getDirectory();
+            this.modelsDir = await this.rootDir.getDirectoryHandle(MODELS_DIR, { create: true });
+            this._isAvailable = true;
+            logger.info('OPFS storage initialized');
+            return true;
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            logger.warning(`OPFS initialization failed: ${msg}`);
+            this._isAvailable = false;
+            return false;
+        }
+    }
+    get isAvailable() {
+        return this._isAvailable === true;
+    }
+    // ---------------------------------------------------------------------------
+    // Core operations
+    // ---------------------------------------------------------------------------
+    /**
+     * Save model data to OPFS.
+     *
+     * Supports nested paths: `saveModel('org/model/file.gguf', data)` creates
+     * `models/org/model/` directories and writes `file.gguf`.
+     *
+     * @param key - Model identifier or nested path (used as filename / path)
+     * @param data - Model file data
+     */
+    async saveModel(key, data) {
+        if (!this.modelsDir)
+            throw new Error('OPFS not initialized. Call initialize() first.');
+        logger.info(`Saving model to OPFS: ${key} (${(data.byteLength / 1024 / 1024).toFixed(1)} MB)`);
+        const dir = await this.resolveParentDir(key, /* create */ true);
+        const filename = this.resolveFilename(key);
+        const fileHandle = await dir.getFileHandle(filename, { create: true });
+        const writable = await fileHandle.createWritable();
+        try {
+            await writable.write(data);
+            await writable.close();
+        }
+        catch (writeError) {
+            // Abort the writable stream instead of closing it (close() throws on errored streams)
+            try {
+                await writable.abort();
+            }
+            catch { /* ignore abort errors */ }
+            // Remove the corrupted 0-byte file so it doesn't poison the cache
+            try {
+                await dir.removeEntry(filename);
+            }
+            catch { /* ignore cleanup errors */ }
+            throw writeError;
+        }
+        logger.info(`Model saved: ${key}`);
+    }
+    /**
+     * Load model data from OPFS.
+     *
+     * @param key - Model identifier or nested path
+     * @returns Model data, or null if not found
+     */
+    async loadModel(key) {
+        if (!this.modelsDir)
+            return null;
+        try {
+            const dir = await this.resolveParentDir(key, /* create */ false);
+            const filename = this.resolveFilename(key);
+            const fileHandle = await dir.getFileHandle(filename);
+            const file = await fileHandle.getFile();
+            logger.info(`Loaded model from OPFS: ${key} (${(file.size / 1024 / 1024).toFixed(1)} MB)`);
+            return await file.arrayBuffer();
+        }
+        catch {
+            return null; // File not found
+        }
+    }
+    /**
+     * Check if a model exists in OPFS.
+     *
+     * @param key - Model identifier or nested path
+     */
+    async hasModel(key) {
+        if (!this.modelsDir)
+            return false;
+        try {
+            const dir = await this.resolveParentDir(key, /* create */ false);
+            const filename = this.resolveFilename(key);
+            await dir.getFileHandle(filename);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Delete a model from OPFS.
+     *
+     * @param key - Model identifier or nested path
+     */
+    async deleteModel(key) {
+        if (!this.modelsDir)
+            return;
+        try {
+            const dir = await this.resolveParentDir(key, /* create */ false);
+            const filename = this.resolveFilename(key);
+            await dir.removeEntry(filename);
+            logger.info(`Deleted model from OPFS: ${key}`);
+        }
+        catch {
+            // File doesn't exist, ignore
+        }
+    }
+    /**
+     * Get the byte size of a stored file without reading it into memory.
+     *
+     * @param key - Model identifier or nested path
+     * @returns File size in bytes, or null if the file doesn't exist
+     */
+    async getFileSize(key) {
+        if (!this.modelsDir)
+            return null;
+        try {
+            const dir = await this.resolveParentDir(key, /* create */ false);
+            const filename = this.resolveFilename(key);
+            const fileHandle = await dir.getFileHandle(filename);
+            const file = await fileHandle.getFile();
+            return file.size;
+        }
+        catch {
+            return null;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Bulk operations
+    // ---------------------------------------------------------------------------
+    /**
+     * List all stored models (top-level files only).
+     */
+    async listModels() {
+        if (!this.modelsDir)
+            return [];
+        const models = [];
+        for await (const [name, handle] of this.modelsDir.entries()) {
+            if (handle.kind === 'file') {
+                const file = await handle.getFile();
+                models.push({
+                    id: name,
+                    sizeBytes: file.size,
+                    lastModified: file.lastModified,
+                });
+            }
+        }
+        return models;
+    }
+    /**
+     * Get total storage usage.
+     */
+    async getStorageUsage() {
+        if (!navigator.storage?.estimate) {
+            return { usedBytes: 0, quotaBytes: 0 };
+        }
+        const estimate = await navigator.storage.estimate();
+        return {
+            usedBytes: estimate.usage ?? 0,
+            quotaBytes: estimate.quota ?? 0,
+        };
+    }
+    /**
+     * Clear all stored models.
+     */
+    async clearAll() {
+        if (!this.rootDir)
+            return;
+        try {
+            await this.rootDir.removeEntry(MODELS_DIR, { recursive: true });
+            this.modelsDir = await this.rootDir.getDirectoryHandle(MODELS_DIR, { create: true });
+            logger.info('All OPFS models cleared');
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            logger.error(`Failed to clear OPFS: ${msg}`);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Metadata persistence (lightweight JSON alongside model files)
+    // ---------------------------------------------------------------------------
+    static METADATA_FILENAME = '_metadata.json';
+    /**
+     * Save model metadata map to OPFS as a small JSON file.
+     * Used for LRU tracking (lastUsedAt timestamps).
+     */
+    async saveMetadata(data) {
+        if (!this.modelsDir)
+            return;
+        try {
+            const json = JSON.stringify(data);
+            const blob = new Blob([json], { type: 'application/json' });
+            const buf = await blob.arrayBuffer();
+            const handle = await this.modelsDir.getFileHandle(OPFSStorage.METADATA_FILENAME, { create: true });
+            const writable = await handle.createWritable();
+            await writable.write(buf);
+            await writable.close();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warning(`Failed to save metadata: ${msg}`);
+        }
+    }
+    /**
+     * Load the persisted metadata map, or return an empty object.
+     */
+    async loadMetadata() {
+        if (!this.modelsDir)
+            return {};
+        try {
+            const handle = await this.modelsDir.getFileHandle(OPFSStorage.METADATA_FILENAME);
+            const file = await handle.getFile();
+            const text = await file.text();
+            return JSON.parse(text);
+        }
+        catch {
+            return {};
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Path resolution helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * For a key that may contain `/`, traverse (and optionally create) the
+     * intermediate directories and return the parent directory handle.
+     *
+     * For a flat key (no `/`) this returns `this.modelsDir` directly.
+     */
+    async resolveParentDir(key, create) {
+        const dir = this.modelsDir;
+        if (!key.includes('/'))
+            return dir;
+        const parts = key.split('/');
+        // All parts except the last are directory segments
+        let current = dir;
+        for (let i = 0; i < parts.length - 1; i++) {
+            current = await current.getDirectoryHandle(parts[i], { create });
+        }
+        return current;
+    }
+    /**
+     * Extract the final filename segment from a key.
+     *
+     * For flat keys this returns a sanitized version of the whole key.
+     * For nested keys (`org/model/file.gguf`) this returns the last segment
+     * with only the filename portion sanitized (directory separators are handled
+     * by `resolveParentDir`).
+     */
+    resolveFilename(key) {
+        const raw = key.includes('/') ? key.split('/').pop() : key;
+        return this.sanitizeFilename(raw);
+    }
+    /**
+     * Sanitize a single filename segment.
+     *
+     * Only strips characters that are invalid in filenames. Keeps `.`, `-`, `_`,
+     * and all alphanumeric characters. This is intentionally lenient compared to
+     * the old implementation which also stripped `/` — directory separators are
+     * now handled structurally by `resolveParentDir`.
+     */
+    sanitizeFilename(name) {
+        // Replace characters that are problematic in filenames across platforms.
+        // Keeps: alphanumeric, dot, dash, underscore, plus, space, parentheses.
+        return name.replace(/[<>:"/\\|?*\x00-\x1F]/g, '_');
+    }
+}
+//# sourceMappingURL=OPFSStorage.js.map

package/dist/Infrastructure/OPFSStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OPFSStorage.js","sourceRoot":"","sources":["../../src/Infrastructure/OPFSStorage.ts"],"names":[],"mappings":"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"}

package/dist/Infrastructure/VLMWorkerBridge.d.ts

@@ -0,0 +1,211 @@
+/**
+ * RunAnywhere Web SDK - VLM Worker Bridge
+ *
+ * Main-thread proxy for the VLM Web Worker. All VLM inference runs off the
+ * main thread so the camera, UI animations, and event loop stay responsive.
+ *
+ * Usage:
+ *   ```typescript
+ *   import { VLMWorkerBridge } from '@runanywhere/web';
+ *
+ *   const vlm = VLMWorkerBridge.shared;
+ *   await vlm.init();
+ *   await vlm.loadModel({ ... });
+ *   const result = await vlm.process(rgbPixels, width, height, prompt, { maxTokens: 100 });
+ *   ```
+ */
+/**
+ * RPC commands sent from the main thread to the Worker.
+ */
+export type VLMWorkerCommand = {
+    type: 'init';
+    id: number;
+    payload: {
+        /** URL to the WASM glue JS (racommons.js or racommons-webgpu.js) */
+        wasmJsUrl: string;
+        /** Whether the loaded module is the WebGPU variant */
+        useWebGPU?: boolean;
+    };
+} | {
+    type: 'load-model';
+    id: number;
+    payload: {
+        modelOpfsKey: string;
+        modelFilename: string;
+        mmprojOpfsKey: string;
+        mmprojFilename: string;
+        modelId: string;
+        modelName: string;
+        /** Optional: raw model data when OPFS doesn't have it (memory-cache fallback). */
+        modelData?: ArrayBuffer;
+        /** Optional: raw mmproj data when OPFS doesn't have it. */
+        mmprojData?: ArrayBuffer;
+    };
+} | {
+    type: 'process';
+    id: number;
+    payload: {
+        rgbPixels: ArrayBuffer;
+        width: number;
+        height: number;
+        prompt: string;
+        maxTokens: number;
+        temperature: number;
+    };
+} | {
+    type: 'cancel';
+    id: number;
+} | {
+    type: 'unload';
+    id: number;
+};
+/**
+ * Result of a VLM inference operation.
+ */
+export interface VLMWorkerResult {
+    text: string;
+    totalTokens: number;
+    promptTokens: number;
+    completionTokens: number;
+    imageTokens: number;
+}
+/**
+ * RPC responses from the Worker to the main thread.
+ */
+export type VLMWorkerResponse = {
+    id: number;
+    type: 'result';
+    payload: any;
+} | {
+    id: number;
+    type: 'error';
+    payload: {
+        message: string;
+    };
+} | {
+    id: number;
+    type: 'progress';
+    payload: {
+        stage: string;
+    };
+};
+/**
+ * Parameters for loading a VLM model in the Worker.
+ */
+export interface VLMLoadModelParams {
+    modelOpfsKey: string;
+    modelFilename: string;
+    mmprojOpfsKey: string;
+    mmprojFilename: string;
+    modelId: string;
+    modelName: string;
+    /** Optional: raw model data when OPFS doesn't have it (memory-cache fallback). */
+    modelData?: ArrayBuffer;
+    /** Optional: raw mmproj data when OPFS doesn't have it. */
+    mmprojData?: ArrayBuffer;
+}
+/**
+ * Options for VLM image processing.
+ */
+export interface VLMProcessOptions {
+    maxTokens?: number;
+    temperature?: number;
+}
+/**
+ * Callback for VLM progress updates (model loading stages, etc.).
+ */
+export type ProgressListener = (stage: string) => void;
+/**
+ * VLMWorkerBridge - Main-thread proxy for VLM Web Worker inference.
+ *
+ * Manages the lifecycle of a dedicated Web Worker that runs VLM inference
+ * in its own WASM instance. Provides:
+ *   - RPC protocol with message ID tracking and promise correlation
+ *   - Auto-recovery from WASM crashes (OOB, stack overflow, etc.)
+ *   - Progress listeners for model loading stages
+ *   - Transferable pixel data for zero-copy image transfer
+ */
+export declare class VLMWorkerBridge {
+    private static _instance;
+    static get shared(): VLMWorkerBridge;
+    private worker;
+    private nextId;
+    private pending;
+    private _isInitialized;
+    private _isModelLoaded;
+    private _progressListeners;
+    /** Saved for auto-recovery after WASM crash */
+    private _lastModelParams;
+    private _needsRecovery;
+    /**
+     * Optional: the app can provide a custom Worker URL or factory.
+     * If not set, the bridge uses the bundled SDK worker entry point.
+     */
+    private _workerUrl;
+    get isInitialized(): boolean;
+    get isModelLoaded(): boolean;
+    /**
+     * Set a custom Worker URL.
+     *
+     * By default the bridge creates a Worker using the SDK's bundled entry point
+     * (`workers/vlm-worker.js`). Apps that need to customise the Worker location
+     * (e.g. different deploy path, or a worker that wraps the runtime) can call
+     * this before `init()`.
+     */
+    set workerUrl(url: URL | string);
+    /**
+     * Subscribe to progress updates from the Worker.
+     * Returns an unsubscribe function.
+     */
+    onProgress(fn: ProgressListener): () => void;
+    private emitProgress;
+    /**
+     * Initialize the Worker and its WASM instance.
+     * Must be called once before loadModel/process.
+     *
+     * Reads the WASM URL and acceleration mode from WASMBridge internally — the
+     * app does not need to pass these.
+     *
+     * @param wasmJsUrl - Optional explicit URL for the WASM glue JS.
+     *                    When omitted, the SDK's WASMBridge.workerWasmUrl is used
+     *                    so the worker loads the exact same variant (WebGPU or CPU)
+     *                    that the main thread successfully loaded.
+     */
+    init(wasmJsUrl?: string): Promise<void>;
+    /**
+     * Load a VLM model in the Worker's WASM instance.
+     *
+     * Normally the Worker reads model files directly from OPFS (zero-copy).
+     * When OPFS quota is exceeded and models are only in the main-thread memory
+     * cache, the data is transferred via postMessage (still zero-copy via
+     * Transferable ArrayBuffers).
+     */
+    loadModel(params: VLMLoadModelParams): Promise<void>;
+    /**
+     * Process an image with the VLM.
+     * Returns a promise that resolves when inference is complete.
+     * The main thread stays responsive during processing.
+     *
+     * The pixel buffer is transferred (zero-copy) to the Worker.
+     */
+    process(rgbPixels: Uint8Array, width: number, height: number, prompt: string, options?: VLMProcessOptions): Promise<VLMWorkerResult>;
+    /**
+     * Recover from a WASM crash by terminating the old Worker,
+     * creating a fresh one, and reloading the model.
+     */
+    private recover;
+    /** Cancel in-progress VLM generation. */
+    cancel(): void;
+    /** Unload the VLM model. */
+    unloadModel(): Promise<void>;
+    /**
+     * Terminate the Worker entirely.
+     *
+     * Rejects any in-flight RPC promises so callers aren't left hanging,
+     * then terminates the underlying Web Worker.
+     */
+    terminate(): void;
+    private send;
+    private handleMessage;
+}
+//# sourceMappingURL=VLMWorkerBridge.d.ts.map

package/dist/Infrastructure/VLMWorkerBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VLMWorkerBridge.d.ts","sourceRoot":"","sources":["../../src/Infrastructure/VLMWorkerBridge.ts"],"names":[],"mappings":"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"}