@runanywhere/web 0.1.0-beta.1

package/dist/Foundation/StructOffsets.js

@@ -0,0 +1,161 @@
+/**
+ * RunAnywhere Web SDK - WASM Struct Field Offsets
+ *
+ * C struct field offsets depend on alignment, padding, pointer size (wasm32
+ * vs wasm64) and compiler flags. Hard-coding them in TypeScript is fragile
+ * and leads to silent data corruption when the C layout changes.
+ *
+ * This module queries `rac_wasm_offsetof_*()` helpers (compiled via
+ * `offsetof()` in wasm_exports.cpp) exactly once after the WASM module is
+ * loaded, and caches the results for the lifetime of the page.
+ *
+ * Usage:
+ *   import { Offsets, loadOffsets } from '../Foundation/StructOffsets';
+ *
+ *   // Called once during SDK init (after WASM load):
+ *   loadOffsets(wasmModule);
+ *
+ *   // Then anywhere:
+ *   m.setValue(optPtr + Offsets.llmOptions.temperature, 0.8, 'float');
+ */
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+let _offsets = null;
+/**
+ * Get the cached struct offsets. Throws if `loadOffsets()` hasn't been called.
+ */
+export function getOffsets() {
+    if (!_offsets) {
+        throw new Error('StructOffsets not loaded — call loadOffsets(module) after WASM init');
+    }
+    return _offsets;
+}
+/**
+ * Convenience re-export so callers can write `Offsets.vlmResult.text`.
+ */
+export const Offsets = new Proxy({}, {
+    get(_target, prop) {
+        return getOffsets()[prop];
+    },
+});
+/**
+ * Read all struct field offsets from the WASM module and cache them.
+ * Must be called exactly once, after the WASM module is loaded.
+ *
+ * @param m - The Emscripten WASM module instance
+ */
+export function loadOffsets(m) {
+    // Helper: safely call an offset function, returning 0 if it doesn't exist
+    // (e.g. when a backend wasn't compiled in).
+    const off = (name) => {
+        const fn = m[`_rac_wasm_offsetof_${name}`];
+        return typeof fn === 'function' ? fn() : 0;
+    };
+    const sz = (name) => {
+        const fn = m[`_rac_wasm_sizeof_${name}`];
+        return typeof fn === 'function' ? fn() : 0;
+    };
+    _offsets = {
+        config: {
+            logLevel: off('config_log_level'),
+        },
+        llmOptions: {
+            maxTokens: off('llm_options_max_tokens'),
+            temperature: off('llm_options_temperature'),
+            topP: off('llm_options_top_p'),
+        },
+        llmResult: {
+            text: off('llm_result_text'),
+            promptTokens: off('llm_result_prompt_tokens'),
+            completionTokens: off('llm_result_completion_tokens'),
+        },
+        vlmImage: {
+            format: off('vlm_image_format'),
+            filePath: off('vlm_image_file_path'),
+            pixelData: off('vlm_image_pixel_data'),
+            base64Data: off('vlm_image_base64_data'),
+            width: off('vlm_image_width'),
+            height: off('vlm_image_height'),
+            dataSize: off('vlm_image_data_size'),
+        },
+        vlmOptions: {
+            maxTokens: off('vlm_options_max_tokens'),
+            temperature: off('vlm_options_temperature'),
+            topP: off('vlm_options_top_p'),
+            streamingEnabled: off('vlm_options_streaming_enabled'),
+            systemPrompt: off('vlm_options_system_prompt'),
+            modelFamily: off('vlm_options_model_family'),
+        },
+        vlmResult: {
+            text: off('vlm_result_text'),
+            promptTokens: off('vlm_result_prompt_tokens'),
+            imageTokens: off('vlm_result_image_tokens'),
+            completionTokens: off('vlm_result_completion_tokens'),
+            totalTokens: off('vlm_result_total_tokens'),
+            timeToFirstTokenMs: off('vlm_result_time_to_first_token_ms'),
+            imageEncodeTimeMs: off('vlm_result_image_encode_time_ms'),
+            totalTimeMs: off('vlm_result_total_time_ms'),
+            tokensPerSecond: off('vlm_result_tokens_per_second'),
+        },
+        structuredOutputConfig: {
+            jsonSchema: off('structured_output_config_json_schema'),
+            includeSchemaInPrompt: off('structured_output_config_include_schema'),
+        },
+        structuredOutputValidation: {
+            isValid: off('structured_output_validation_is_valid'),
+            errorMessage: off('structured_output_validation_error_message'),
+            extractedJson: off('structured_output_validation_extracted_json'),
+        },
+        embeddingsOptions: {
+            normalize: off('embeddings_options_normalize'),
+            pooling: off('embeddings_options_pooling'),
+            nThreads: off('embeddings_options_n_threads'),
+        },
+        embeddingsResult: {
+            embeddings: off('embeddings_result_embeddings'),
+            numEmbeddings: off('embeddings_result_num_embeddings'),
+            dimension: off('embeddings_result_dimension'),
+            processingTimeMs: off('embeddings_result_processing_time_ms'),
+            totalTokens: off('embeddings_result_total_tokens'),
+        },
+        embeddingVector: {
+            data: off('embedding_vector_data'),
+            dimension: off('embedding_vector_dimension'),
+            structSize: sz('embedding_vector'),
+        },
+        diffusionOptions: {
+            prompt: off('diffusion_options_prompt'),
+            negativePrompt: off('diffusion_options_negative_prompt'),
+            width: off('diffusion_options_width'),
+            height: off('diffusion_options_height'),
+            steps: off('diffusion_options_steps'),
+            guidanceScale: off('diffusion_options_guidance_scale'),
+            seed: off('diffusion_options_seed'),
+            scheduler: off('diffusion_options_scheduler'),
+            mode: off('diffusion_options_mode'),
+            denoiseStrength: off('diffusion_options_denoise_strength'),
+            reportIntermediate: off('diffusion_options_report_intermediate'),
+            progressStride: off('diffusion_options_progress_stride'),
+        },
+        diffusionResult: {
+            imageData: off('diffusion_result_image_data'),
+            imageSize: off('diffusion_result_image_size'),
+            width: off('diffusion_result_width'),
+            height: off('diffusion_result_height'),
+            seedUsed: off('diffusion_result_seed_used'),
+            generationTimeMs: off('diffusion_result_generation_time_ms'),
+            safetyFlagged: off('diffusion_result_safety_flagged'),
+        },
+    };
+}
+/**
+ * Load offsets for a standalone WASM module (e.g. in a Web Worker).
+ * Returns the offsets directly instead of storing them in the singleton.
+ * Useful when the Worker has its own WASM instance.
+ */
+export function loadOffsetsFromModule(m) {
+    loadOffsets(m);
+    return _offsets;
+}
+//# sourceMappingURL=StructOffsets.js.map

package/dist/Foundation/StructOffsets.js.map

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

package/dist/Foundation/WASMBridge.d.ts

@@ -0,0 +1,241 @@
+/**
+ * RunAnywhere Web SDK - WASM Bridge
+ *
+ * Loads the RACommons WASM module and provides typed wrappers
+ * around the C API functions. This is the web equivalent of:
+ *   - CppBridge.swift (iOS)
+ *   - CppBridge.kt (Kotlin/Android)
+ *   - dart_bridge.dart (Flutter)
+ *   - HybridRunAnywhereCore.cpp (React Native)
+ */
+/** The hardware acceleration mode used by the loaded WASM module. */
+export type AccelerationMode = 'webgpu' | 'cpu';
+/**
+ * Emscripten module interface.
+ * Defines the functions available on the loaded WASM module.
+ */
+export interface RACommonsModule extends EmscriptenModule {
+    ccall: typeof ccall;
+    cwrap: typeof cwrap;
+    addFunction: (func: (...args: number[]) => number | void, signature: string) => number;
+    removeFunction: (ptr: number) => void;
+    UTF8ToString: (ptr: number, maxBytesToRead?: number) => string;
+    stringToUTF8: (str: string, outPtr: number, maxBytesToWrite: number) => void;
+    lengthBytesUTF8: (str: string) => number;
+    setValue: (ptr: number, value: number, type: string) => void;
+    getValue: (ptr: number, type: string) => number;
+    FS: typeof FS;
+    _malloc: (size: number) => number;
+    _free: (ptr: number) => void;
+    _rac_init: (configPtr: number) => number;
+    _rac_shutdown: () => void;
+    _rac_is_initialized: () => number;
+    _rac_configure_logging: (environment: number) => number;
+    _rac_set_platform_adapter: (adapterPtr: number) => number;
+    _rac_log: (level: number, categoryPtr: number, messagePtr: number) => void;
+    _rac_event_subscribe: (category: number, callbackPtr: number, userDataPtr: number) => number;
+    _rac_event_subscribe_all: (callbackPtr: number, userDataPtr: number) => number;
+    _rac_event_unsubscribe: (subscriptionId: number) => void;
+    _rac_event_track: (type: number, category: number, destination: number, propsJsonPtr: number) => number;
+    _rac_error_message: (code: number) => number;
+    _rac_model_registry_create: (outHandlePtr: number) => number;
+    _rac_model_registry_destroy: (handle: number) => void;
+    _rac_model_registry_get_all: (handle: number, outModelsPtr: number, outCountPtr: number) => number;
+    _rac_model_info_free: (modelPtr: number) => void;
+    _rac_model_info_array_free: (modelsPtr: number, count: number) => void;
+    _rac_llm_component_create: (outHandlePtr: number) => number;
+    _rac_llm_component_configure: (handle: number, configPtr: number) => number;
+    _rac_llm_component_load_model: (handle: number, pathPtr: number, idPtr: number, namePtr: number) => number;
+    _rac_llm_component_unload: (handle: number) => number;
+    _rac_llm_component_is_loaded: (handle: number) => number;
+    _rac_llm_component_generate: (handle: number, promptPtr: number, optionsPtr: number, outResultPtr: number) => number;
+    _rac_llm_component_generate_stream: (handle: number, promptPtr: number, optionsPtr: number, tokenCb: number, completeCb: number, errorCb: number, userData: number) => number;
+    _rac_llm_component_cancel: (handle: number) => number;
+    _rac_llm_component_get_model_id: (handle: number) => number;
+    _rac_llm_component_get_state: (handle: number) => number;
+    _rac_llm_component_destroy: (handle: number) => void;
+    _rac_llm_result_free: (resultPtr: number) => void;
+    _rac_vlm_component_create: (outHandlePtr: number) => number;
+    _rac_vlm_component_load_model: (handle: number, modelPath: number, mmprojPath: number, modelId: number, modelName: number) => number;
+    _rac_vlm_component_process: (handle: number, imagePtr: number, promptPtr: number, optionsPtr: number, resultPtr: number) => number;
+    _rac_vlm_component_is_loaded: (handle: number) => number;
+    _rac_vlm_component_destroy: (handle: number) => void;
+    _rac_vlm_component_cancel: (handle: number) => void;
+    _rac_vlm_result_free: (resultPtr: number) => void;
+    _rac_backend_llamacpp_vlm_register: () => number;
+    _rac_backend_llamacpp_vlm_unregister: () => void;
+    _rac_wasm_ping: () => number;
+    _rac_wasm_sizeof_platform_adapter: () => number;
+    _rac_wasm_sizeof_config: () => number;
+    _rac_wasm_sizeof_llm_options: () => number;
+    _rac_wasm_sizeof_llm_result: () => number;
+    _rac_wasm_create_llm_options_default: () => number;
+    _rac_wasm_sizeof_vlm_image: () => number;
+    _rac_wasm_sizeof_vlm_options: () => number;
+    _rac_wasm_sizeof_vlm_result: () => number;
+    _rac_wasm_sizeof_diffusion_options: () => number;
+    _rac_wasm_sizeof_diffusion_result: () => number;
+    _rac_wasm_sizeof_embeddings_options: () => number;
+    _rac_wasm_sizeof_embeddings_result: () => number;
+    _rac_wasm_sizeof_structured_output_config: () => number;
+    _rac_wasm_sizeof_voice_agent_config: () => number;
+    _rac_wasm_sizeof_voice_agent_result: () => number;
+    _rac_wasm_sizeof_stt_options: () => number;
+    _rac_wasm_sizeof_stt_result: () => number;
+    _rac_wasm_sizeof_tts_options: () => number;
+    _rac_wasm_sizeof_tts_result: () => number;
+    _rac_wasm_sizeof_vad_config: () => number;
+    _rac_sdk_init: (configPtr: number) => number;
+    _rac_sdk_is_initialized: () => number;
+    _rac_sdk_reset: () => void;
+    _rac_telemetry_manager_create: (env: number, deviceIdPtr: number, platformPtr: number, versionPtr: number) => number;
+    _rac_telemetry_manager_destroy: (manager: number) => void;
+}
+/**
+ * WASMBridge - Loads and manages the RACommons WASM module.
+ *
+ * Singleton that provides access to all RACommons C API functions
+ * compiled to WebAssembly. This is the central point through which
+ * all SDK operations flow, identical to CppBridge on mobile platforms.
+ */
+export declare class WASMBridge {
+    private static _instance;
+    private _module;
+    private _loaded;
+    private _loading;
+    private _accelerationMode;
+    /** The URL that was used to load the WASM glue JS (for worker reuse). */
+    private _loadedModuleUrl;
+    static get shared(): WASMBridge;
+    /** Whether the WASM module is loaded */
+    get isLoaded(): boolean;
+    /** Get the raw Emscripten module (throws if not loaded) */
+    get module(): RACommonsModule;
+    /** The hardware acceleration mode in use (webgpu or cpu). */
+    get accelerationMode(): AccelerationMode;
+    /**
+     * The URL of the WASM glue JS that was successfully loaded.
+     * Web Workers should use this URL to load the same WASM variant
+     * (WebGPU or CPU) that the main thread is using.
+     *
+     * Returns `null` if `load()` has not been called yet.
+     */
+    get workerWasmUrl(): string | null;
+    /**
+     * Load the RACommons WASM module.
+     *
+     * Detects WebGPU at init time and loads the appropriate build variant:
+     *   - `racommons-webgpu.js` when WebGPU + JSPI are available
+     *   - `racommons.js` as the CPU-only fallback
+     *
+     * Safe to call concurrently -- only the first caller triggers the actual
+     * load; subsequent callers await the same in-flight promise.
+     *
+     * @param wasmUrl        - URL to the CPU-only racommons.js glue file.
+     * @param webgpuWasmUrl  - URL to the WebGPU racommons-webgpu.js glue file.
+     * @param acceleration   - Force a specific mode ('auto' detects, 'webgpu' forces GPU, 'cpu' forces CPU).
+     */
+    load(wasmUrl?: string, webgpuWasmUrl?: string, acceleration?: 'auto' | 'webgpu' | 'cpu'): Promise<void>;
+    /**
+     * Internal load implementation.
+     * Separated from `load()` so the concurrent-load guard can wrap it.
+     */
+    private _doLoad;
+    /**
+     * Determine whether to use WebGPU based on the acceleration preference
+     * and actual browser capability.
+     */
+    private resolveAcceleration;
+    /**
+     * Probe for a functional WebGPU adapter.
+     * Returns true only when the browser exposes navigator.gpu AND
+     * a valid adapter can be obtained.
+     */
+    static detectWebGPU(): Promise<boolean>;
+    /**
+     * Detect JSPI (JavaScript Promise Integration) support.
+     * The WebGPU WASM module requires WebAssembly.promising and
+     * WebAssembly.Suspending to suspend during async GPU operations.
+     */
+    static detectJSPI(): boolean;
+    /** Allocate a C string in WASM memory. Caller must free. */
+    allocString(str: string): number;
+    /** Read a C string from WASM memory */
+    readString(ptr: number): string;
+    /** Free WASM memory */
+    free(ptr: number): void;
+    /**
+     * Write a Uint8Array into WASM linear memory at `destPtr`.
+     *
+     * Fast path uses `HEAPU8.set()` when available (after WASM rebuild).
+     * Fallback uses `setValue` byte-by-byte (works with any build).
+     */
+    writeBytes(src: Uint8Array, destPtr: number): void;
+    /**
+     * Read `length` bytes from WASM linear memory starting at `srcPtr`.
+     *
+     * Fast path uses `HEAPU8.slice()` when available.
+     * Fallback uses `getValue` byte-by-byte.
+     */
+    readBytes(srcPtr: number, length: number): Uint8Array;
+    /**
+     * Read `count` float32 values from WASM linear memory starting at `srcPtr`.
+     *
+     * Fast path uses `HEAPF32` when available.
+     * Fallback reads 4 bytes at a time via getValue('float').
+     */
+    readFloat32Array(srcPtr: number, count: number): Float32Array;
+    /**
+     * Write a Float32Array into WASM linear memory at `destPtr`.
+     * `destPtr` must be 4-byte aligned.
+     *
+     * Fast path uses `HEAPF32.set()` when available.
+     * Fallback uses `setValue` with 'float'.
+     */
+    writeFloat32Array(src: Float32Array, destPtr: number): void;
+    /**
+     * Read a single float32 value from WASM linear memory.
+     */
+    readFloat32(ptr: number): number;
+    /** Check a rac_result_t and throw SDKError if not success */
+    checkResult(result: number, operation: string): void;
+    /** Get RACommons error message for a result code */
+    getErrorMessage(resultCode: number): string;
+    /**
+     * Type-safe wrapper around Emscripten ccall().
+     * Centralizes all dynamic WASM function calls through the bridge.
+     */
+    callFunction<T = number>(funcName: string, returnType: string | null, argTypes: string[], args: unknown[], opts?: {
+        async?: boolean;
+    }): T;
+    /**
+     * Call a WASM function that returns rac_result_t and throw SDKError if
+     * the result is non-zero.
+     */
+    callWithCheck(funcName: string, argTypes: string[], args: unknown[]): void;
+    /** Shutdown the WASM module */
+    shutdown(): void;
+}
+export type { EmscriptenModule };
+declare function ccall(ident: string, returnType: string | null, argTypes: string[], args: unknown[], opts?: object): unknown;
+declare function cwrap(ident: string, returnType: string | null, argTypes: string[]): (...args: unknown[]) => unknown;
+declare const FS: {
+    mkdir: (path: string) => void;
+    writeFile: (path: string, data: Uint8Array) => void;
+    readFile: (path: string) => Uint8Array;
+    unlink: (path: string) => void;
+    stat: (path: string) => {
+        size: number;
+    };
+    analyzePath: (path: string) => {
+        exists: boolean;
+    };
+    mount: (type: unknown, opts: unknown, mountpoint: string) => void;
+    syncfs: (populate: boolean, callback: (err: unknown) => void) => void;
+};
+interface EmscriptenModule {
+    onRuntimeInitialized?: () => void;
+    print?: (text: string) => void;
+    printErr?: (text: string) => void;
+}
+//# sourceMappingURL=WASMBridge.d.ts.map

package/dist/Foundation/WASMBridge.d.ts.map

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