@runanywhere/web-llamacpp 0.1.0-beta.10

package/dist/Infrastructure/VLMWorkerBridge.d.ts

@@ -0,0 +1,219 @@
+/**
+ * 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;
+        topP: number;
+        systemPrompt?: string;
+        modelFamily?: 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 via the Worker bridge.
+ */
+export interface VLMProcessOptions {
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    /** System prompt prepended to the user prompt inside the Worker. */
+    systemPrompt?: string;
+    /** Model family enum value (maps to rac_vlm_model_family_t). 0 = auto-detect. */
+    modelFamily?: 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 LlamaCppBridge internally —
+     * the app does not need to pass these.
+     *
+     * @param wasmJsUrl - Optional explicit URL for the WASM glue JS.
+     *                    When omitted, the SDK's LlamaCppBridge.wasmUrl 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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"}

package/dist/Infrastructure/VLMWorkerBridge.js

@@ -0,0 +1,288 @@
+/**
+ * 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 });
+ *   ```
+ */
+import { SDKLogger } from '@runanywhere/web';
+import { LlamaCppBridge } from '../Foundation/LlamaCppBridge';
+// ---------------------------------------------------------------------------
+// Bridge
+// ---------------------------------------------------------------------------
+const logger = new SDKLogger('VLMWorkerBridge');
+/**
+ * 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 class VLMWorkerBridge {
+    // ---- Singleton ----
+    static _instance = null;
+    static get shared() {
+        if (!VLMWorkerBridge._instance) {
+            VLMWorkerBridge._instance = new VLMWorkerBridge();
+        }
+        return VLMWorkerBridge._instance;
+    }
+    // ---- State ----
+    worker = null;
+    nextId = 0;
+    pending = new Map();
+    _isInitialized = false;
+    _isModelLoaded = false;
+    _progressListeners = [];
+    /** Saved for auto-recovery after WASM crash */
+    _lastModelParams = null;
+    _needsRecovery = false;
+    /**
+     * Optional: the app can provide a custom Worker URL or factory.
+     * If not set, the bridge uses the bundled SDK worker entry point.
+     */
+    _workerUrl = null;
+    get isInitialized() { return this._isInitialized; }
+    get isModelLoaded() { return this._isModelLoaded; }
+    // ---- Configuration ----
+    /**
+     * 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) {
+        this._workerUrl = url;
+    }
+    // ---- Progress ----
+    /**
+     * Subscribe to progress updates from the Worker.
+     * Returns an unsubscribe function.
+     */
+    onProgress(fn) {
+        this._progressListeners.push(fn);
+        return () => {
+            this._progressListeners = this._progressListeners.filter((l) => l !== fn);
+        };
+    }
+    emitProgress(stage) {
+        for (const fn of this._progressListeners)
+            fn(stage);
+    }
+    // ---- Lifecycle ----
+    /**
+     * Initialize the Worker and its WASM instance.
+     * Must be called once before loadModel/process.
+     *
+     * Reads the WASM URL and acceleration mode from LlamaCppBridge internally —
+     * the app does not need to pass these.
+     *
+     * @param wasmJsUrl - Optional explicit URL for the WASM glue JS.
+     *                    When omitted, the SDK's LlamaCppBridge.wasmUrl is used
+     *                    so the worker loads the exact same variant (WebGPU or CPU)
+     *                    that the main thread successfully loaded.
+     */
+    async init(wasmJsUrl) {
+        if (this._isInitialized)
+            return;
+        // All acceleration logic lives in the SDK's LlamaCppBridge.
+        // We just read the decision it already made.
+        const bridge = LlamaCppBridge.shared;
+        const useWebGPU = bridge.accelerationMode === 'webgpu';
+        const resolvedUrl = wasmJsUrl ?? bridge.wasmUrl ?? '';
+        if (!resolvedUrl) {
+            throw new Error('[VLMWorkerBridge] SDK not initialized — no WASM URL available');
+        }
+        // Create the Worker
+        const workerUrl = this._workerUrl ?? new URL('../workers/vlm-worker.js', import.meta.url);
+        this.worker = new Worker(workerUrl, { type: 'module' });
+        this.worker.onmessage = this.handleMessage.bind(this);
+        this.worker.onerror = (e) => {
+            logger.error(`Worker error: ${e.message ?? e}`);
+        };
+        await this.send('init', { wasmJsUrl: resolvedUrl, useWebGPU });
+        this._isInitialized = true;
+        logger.info(`Worker initialized (${useWebGPU ? 'WebGPU' : 'CPU'})`);
+    }
+    /**
+     * 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).
+     */
+    async loadModel(params) {
+        if (!this._isInitialized) {
+            await this.init();
+        }
+        // M-RoPE models (Qwen2-VL) produce NaN logits on WebGPU due to f16
+        // accumulation overflow in the rotary position encoding shader. If we
+        // detect one, restart the Worker with the CPU WASM binary so the entire
+        // inference runs on the CPU backend.
+        //
+        // PERFORMANCE: The CPU WASM binary is single-threaded (pthreads OFF), so
+        // Qwen2-VL runs at ~1 tok/s vs ~15-20 tok/s for WebGPU models (LFM2-VL).
+        // This is a correctness-over-speed trade-off.
+        // TODO: re-test on WebGPU periodically as llama.cpp's WebGPU backend
+        // matures — the Vulkan fp16 FA fix (b8168) may eventually be ported.
+        const bridge = LlamaCppBridge.shared;
+        const isQwenVL = /qwen/i.test(params.modelId) || /qwen/i.test(params.modelName);
+        if (isQwenVL && bridge.accelerationMode === 'webgpu') {
+            const currentUrl = bridge.wasmUrl ?? '';
+            const cpuUrl = currentUrl.replace(/-webgpu\.js$/, '.js');
+            if (cpuUrl !== currentUrl) {
+                logger.info('Qwen2-VL detected — restarting VLM Worker with CPU WASM (M-RoPE compat)');
+                this.terminate();
+                await this.init(cpuUrl);
+            }
+        }
+        // Transfer data buffers when provided (zero-copy to Worker)
+        const transferables = [];
+        if (params.modelData)
+            transferables.push(params.modelData);
+        if (params.mmprojData)
+            transferables.push(params.mmprojData);
+        await this.send('load-model', params, transferables);
+        this._isModelLoaded = true;
+        this._lastModelParams = params;
+        this._needsRecovery = false;
+        logger.info(`Model loaded: ${params.modelId}`);
+    }
+    /**
+     * 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.
+     */
+    async process(rgbPixels, width, height, prompt, options = {}) {
+        // Auto-recover from previous WASM crash (OOB, etc.)
+        if (this._needsRecovery) {
+            await this.recover();
+        }
+        if (!this._isModelLoaded) {
+            throw new Error('No VLM model loaded in Worker. Call loadModel() first.');
+        }
+        // Transfer the pixel buffer (zero-copy to Worker)
+        const buffer = rgbPixels.buffer.slice(rgbPixels.byteOffset, rgbPixels.byteOffset + rgbPixels.byteLength);
+        try {
+            return await this.send('process', {
+                rgbPixels: buffer,
+                width,
+                height,
+                prompt,
+                maxTokens: options.maxTokens ?? 200,
+                temperature: options.temperature ?? 0.7,
+                topP: options.topP ?? 0.9,
+                systemPrompt: options.systemPrompt,
+                modelFamily: options.modelFamily,
+            }, [buffer]);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // WASM runtime errors (OOB, stack overflow) leave the instance corrupted.
+            // Mark for recovery so the next call creates a fresh Worker.
+            if (msg.includes('memory access out of bounds') ||
+                msg.includes('unreachable') ||
+                msg.includes('RuntimeError')) {
+                logger.warning('WASM crash detected, will recover on next call');
+                this._needsRecovery = true;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Recover from a WASM crash by terminating the old Worker,
+     * creating a fresh one, and reloading the model.
+     */
+    async recover() {
+        if (!this._lastModelParams) {
+            throw new Error('Cannot recover: no model params saved');
+        }
+        logger.info('Recovering from WASM crash...');
+        const params = this._lastModelParams;
+        // Destroy old worker completely
+        this.terminate();
+        // Reinitialize fresh worker + reload model
+        await this.init();
+        await this.loadModel(params);
+        logger.info('Recovery complete');
+    }
+    /** Cancel in-progress VLM generation. */
+    cancel() {
+        if (this.worker) {
+            this.worker.postMessage({ type: 'cancel', id: -2 });
+        }
+    }
+    /** Unload the VLM model. */
+    async unloadModel() {
+        if (!this._isModelLoaded)
+            return;
+        await this.send('unload', {});
+        this._isModelLoaded = false;
+    }
+    /**
+     * Terminate the Worker entirely.
+     *
+     * Rejects any in-flight RPC promises so callers aren't left hanging,
+     * then terminates the underlying Web Worker.
+     */
+    terminate() {
+        // Reject all pending RPC calls so callers don't hang forever
+        for (const [, { reject }] of this.pending) {
+            reject(new Error('VLM Worker terminated'));
+        }
+        this.pending.clear();
+        this.worker?.terminate();
+        this.worker = null;
+        this._isInitialized = false;
+        this._isModelLoaded = false;
+    }
+    // ---- Internal RPC ----
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    send(type, payload, transferables) {
+        return new Promise((resolve, reject) => {
+            if (!this.worker) {
+                reject(new Error('VLM Worker not initialized'));
+                return;
+            }
+            const id = this.nextId++;
+            this.pending.set(id, { resolve, reject });
+            this.worker.postMessage({ type, id, payload }, transferables ?? []);
+        });
+    }
+    handleMessage(e) {
+        const { id, type, payload } = e.data;
+        // Progress messages (id=-1) are not RPC responses
+        if (type === 'progress') {
+            this.emitProgress(payload.stage);
+            return;
+        }
+        const pending = this.pending.get(id);
+        if (!pending)
+            return;
+        this.pending.delete(id);
+        if (type === 'error') {
+            pending.reject(new Error(payload.message));
+        }
+        else {
+            pending.resolve(payload);
+        }
+    }
+}
+//# sourceMappingURL=VLMWorkerBridge.js.map

package/dist/Infrastructure/VLMWorkerBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VLMWorkerBridge.js","sourceRoot":"","sources":["../../src/Infrastructure/VLMWorkerBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AA4F9D,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,iBAAiB,CAAC,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,OAAO,eAAe;IAC1B,sBAAsB;IACd,MAAM,CAAC,SAAS,GAA2B,IAAI,CAAC;IAExD,MAAM,KAAK,MAAM;QACf,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,CAAC;YAC/B,eAAe,CAAC,SAAS,GAAG,IAAI,eAAe,EAAE,CAAC;QACpD,CAAC;QACD,OAAO,eAAe,CAAC,SAAS,CAAC;IACnC,CAAC;IAED,kBAAkB;IACV,MAAM,GAAkB,IAAI,CAAC;IAC7B,MAAM,GAAG,CAAC,CAAC;IACX,OAAO,GAAG,IAAI,GAAG,EAAqE,CAAC;IACvF,cAAc,GAAG,KAAK,CAAC;IACvB,cAAc,GAAG,KAAK,CAAC;IACvB,kBAAkB,GAAuB,EAAE,CAAC;IACpD,+CAA+C;IACvC,gBAAgB,GAA8B,IAAI,CAAC;IACnD,cAAc,GAAG,KAAK,CAAC;IAE/B;;;OAGG;IACK,UAAU,GAAwB,IAAI,CAAC;IAE/C,IAAI,aAAa,KAAc,OAAO,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;IAC5D,IAAI,aAAa,KAAc,OAAO,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;IAE5D,0BAA0B;IAE1B;;;;;;;OAOG;IACH,IAAI,SAAS,CAAC,GAAiB;QAC7B,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;IACxB,CAAC;IAED,qBAAqB;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAoB;QAC7B,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QAC5E,CAAC,CAAC;IACJ,CAAC;IAEO,YAAY,CAAC,KAAa;QAChC,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,kBAAkB;YAAE,EAAE,CAAC,KAAK,CAAC,CAAC;IACtD,CAAC;IAED,sBAAsB;IAEtB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,IAAI,CAAC,SAAkB;QAC3B,IAAI,IAAI,CAAC,cAAc;YAAE,OAAO;QAEhC,4DAA4D;QAC5D,6CAA6C;QAC7C,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC;QACrC,MAAM,SAAS,GAAG,MAAM,CAAC,gBAAgB,KAAK,QAAQ,CAAC;QACvD,MAAM,WAAW,GAAG,SAAS,IAAI,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;QAEtD,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QACnF,CAAC;QAED,oBAAoB;QACpB,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,GAAG,CAAC,0BAA0B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1F,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAExD,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,EAAE;YAC1B,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,OAAO,IAAI,CAAC,EAAE,CAAC,CAAC;QAClD,CAAC,CAAC;QAEF,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,MAAM,CAAC,IAAI,CAAC,uBAAuB,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;IACtE,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,SAAS,CAAC,MAA0B;QACxC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC;QAED,mEAAmE;QACnE,sEAAsE;QACtE,wEAAwE;QACxE,qCAAqC;QACrC,EAAE;QACF,yEAAyE;QACzE,yEAAyE;QACzE,8CAA8C;QAC9C,qEAAqE;QACrE,qEAAqE;QACrE,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAChF,IAAI,QAAQ,IAAI,MAAM,CAAC,gBAAgB,KAAK,QAAQ,EAAE,CAAC;YACrD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;YACzD,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC1B,MAAM,CAAC,IAAI,CAAC,yEAAyE,CAAC,CAAC;gBACvF,IAAI,CAAC,SAAS,EAAE,CAAC;gBACjB,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,4DAA4D;QAC5D,MAAM,aAAa,GAAmB,EAAE,CAAC;QACzC,IAAI,MAAM,CAAC,SAAS;YAAE,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC3D,IAAI,MAAM,CAAC,UAAU;YAAE,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAE7D,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;QACrD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC;QAC/B,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;QAC5B,MAAM,CAAC,IAAI,CAAC,iBAAiB,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CACX,SAAqB,EACrB,KAAa,EACb,MAAc,EACd,MAAc,EACd,UAA6B,EAAE;QAE/B,oDAAoD;QACpD,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACvB,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;QAED,kDAAkD;QAClD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,CACnC,SAAS,CAAC,UAAU,EACpB,SAAS,CAAC,UAAU,GAAG,SAAS,CAAC,UAAU,CAC5C,CAAC;QAEF,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,IAAI,CACpB,SAAS,EACT;gBACE,SAAS,EAAE,MAAM;gBACjB,KAAK;gBACL,MAAM;gBACN,MAAM;gBACN,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,GAAG;gBACnC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,GAAG;gBACvC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,GAAG;gBACzB,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,WAAW,EAAE,OAAO,CAAC,WAAW;aACjC,EACD,CAAC,MAAM,CAAC,CACT,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,0EAA0E;YAC1E,6DAA6D;YAC7D,IAAI,GAAG,CAAC,QAAQ,CAAC,6BAA6B,CAAC;gBAC3C,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC;gBAC3B,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBACjC,MAAM,CAAC,OAAO,CAAC,gDAAgD,CAAC,CAAC;gBACjE,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;YAC7B,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,OAAO;QACnB,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,CAAC;QAErC,gCAAgC;QAChC,IAAI,CAAC,SAAS,EAAE,CAAC;QAEjB,2CAA2C;QAC3C,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACnC,CAAC;IAED,yCAAyC;IACzC,MAAM;QACJ,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED,4BAA4B;IAC5B,KAAK,CAAC,WAAW;QACf,IAAI,CAAC,IAAI,CAAC,cAAc;YAAE,OAAO;QACjC,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED;;;;;OAKG;IACH,SAAS;QACP,6DAA6D;QAC7D,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC1C,MAAM,CAAC,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAErB,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;QAC5B,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED,yBAAyB;IAEzB,uDAAuD;IAC/C,IAAI,CAAC,IAAY,EAAE,OAAY,EAAE,aAA8B;QACrE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACjB,MAAM,CAAC,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC,CAAC;gBAChD,OAAO;YACT,CAAC;YAED,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAC1C,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,aAAa,IAAI,EAAE,CAAC,CAAC;QACtE,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,aAAa,CAAC,CAAkC;QACtD,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC;QAErC,kDAAkD;QAClD,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACxB,IAAI,CAAC,YAAY,CAAE,OAAe,CAAC,KAAK,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAExB,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrB,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAE,OAAe,CAAC,OAAO,CAAC,CAAC,CAAC;QACtD,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC"}

package/dist/Infrastructure/VLMWorkerRuntime.d.ts

@@ -0,0 +1,38 @@
+/**
+ * RunAnywhere Web SDK - VLM Worker Runtime
+ *
+ * Encapsulates the Worker-side logic for VLM inference. This module runs
+ * inside a dedicated Web Worker and manages its own WASM instance
+ * (separate from the main-thread SDK).
+ *
+ * Architecture:
+ *   - Loads its OWN WASM instance (separate from the main thread SDK)
+ *   - Reads model files from OPFS directly (no large postMessage transfers)
+ *   - Communicates via typed postMessage RPC
+ *
+ * Why a separate WASM instance?
+ *   The C function `rac_vlm_component_process` is synchronous and blocks for
+ *   ~100s (2B model in WASM). Running it on the main thread freezes the entire UI.
+ *   A Worker with its own WASM instance allows inference to happen concurrently.
+ *
+ * IMPORTANT: This file must NOT import from WASMBridge.ts or other SDK modules
+ * that assume a main-thread context. The Worker has its own WASM instance and
+ * should be self-contained. Only `type`-only imports are safe.
+ */
+import type { VLMWorkerResult } from './VLMWorkerBridge';
+export type { VLMWorkerResult };
+/**
+ * Start the VLM Worker runtime.
+ *
+ * Call this once from the Worker entry point. It sets up the `self.onmessage`
+ * handler that processes RPC commands from the main-thread VLMWorkerBridge.
+ *
+ * @example
+ * ```typescript
+ * // workers/vlm-worker.ts
+ * import { startVLMWorkerRuntime } from '../Infrastructure/VLMWorkerRuntime';
+ * startVLMWorkerRuntime();
+ * ```
+ */
+export declare function startVLMWorkerRuntime(): void;
+//# sourceMappingURL=VLMWorkerRuntime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VLMWorkerRuntime.d.ts","sourceRoot":"","sources":["../../src/Infrastructure/VLMWorkerRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,KAAK,EAAuC,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAI9F,YAAY,EAAE,eAAe,EAAE,CAAC;AAirBhC;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C"}