WebAssembly (WASM) Bridge

Relevant source files

The following files were used as context for generating this wiki page:

• oxidize-core/src/util/web_worker.rs
• oxidize-c/src/util/wasm_bridge.c
• oxidize-c/include/oxidize/wasm.h
• oxidize-core/src/lib.rs
• oxidize-c/tests/test_wasm.c
• oxidize-core/web-demo/app.js
• PRD.md

The WebAssembly (WASM) Bridge provides a high-performance interface for running Large Language Model (LLM) inference directly within web browsers. It acts as a communication layer between JavaScript environments and the core Rust inference engine, enabling local-first AI applications without server-side dependencies.

The bridge supports model loading, token generation with streaming capabilities, and hardware-accelerated backends such as WebGPU. It utilizes wasm-bindgen for Rust-to-JS bindings and includes a dedicated C11 port for dependency-free environments, ensuring broad compatibility across different web runtimes and WebWorker threads.

Sources: PRD.md:20-30, oxidize-c/include/oxidize/wasm.h:1-15, oxidize-core/src/lib.rs:200-210

Architecture and Components

The WASM Bridge follows a "Config + State + Message" pattern to manage the lifecycle of an inference session. It operates primarily within WebWorker threads to prevent blocking the main browser UI during intensive compute tasks.

Core Structure

The bridge manages internal state through an opaque handle that tracks model status, lifetime statistics, and message queues.

Messaging System

The bridge implements an asynchronous messaging protocol to handle host requests. This mirrors the postMessage architecture used in standard browser WebWorkers.

Message Type	Description
OC_WASM_MSG_LOAD	Loads a model from a specified path or URL.
OC_WASM_MSG_GENERATE	Triggers the forward pass and sampling for a prompt.
OC_WASM_MSG_CANCEL	Aborts an in-flight generation task.
OC_WASM_MSG_STATUS	Retrieves a snapshot of current bridge statistics.

Sources: oxidize-c/include/oxidize/wasm.h:47-53, oxidize-c/src/util/wasm_bridge.c:300-320

Inference Lifecycle

The inference process begins with bridge initialization and model loading, followed by token generation iterations.

Initialization and Loading

Initialization sets memory limits and hardware features. The bridge enforces a default memory limit of 2 GiB to align with browser constraints.

1. Call oc_wasm_bridge_init with desired configuration.
2. Load weights via oc_wasm_bridge_load_model (path/URL) or oc_wasm_bridge_load_model_bytes (memory buffer).
3. The bridge validates the GGUF header and allocates the KV cache.

Sources: oxidize-c/include/oxidize/wasm.h:26-28, oxidize-c/src/util/wasm_bridge.c:135-160

Generation Flow

Generation produces tokens until a stop condition occurs. A stop condition includes reaching max_tokens, encountering an EOS token, user cancellation, or a callback returning false.

TypeScript Bindings

The bridge exposes a custom TypeScript interface contract that must be mirrored by the host application to ensure type-safe communication. This contract defines the data structures for inference requests and stream chunks.

Interface Definitions

The bridge provides oc_wasm_bridge_interface_string() to emit these declarations as a static string.

export interface OxidizeWasmStats {
  tokens_generated: number;
  tokens_consumed: number;
  tokens_per_sec: number;
  memory_used: number;
  model_loaded: boolean;
}

export interface OxidizeWorkerStreamChunk {
  token: number;
  index: number;
}

Sources: oxidize-c/src/util/wasm_bridge.c:390-445, oxidize-core/src/util/web_worker.rs

Performance and Resource Management

The WASM Bridge includes specific mechanisms to monitor and limit resource usage within the browser environment.

• Memory Accounting: Tracks alloc_bytes and memory_peak. On platforms supporting it, the bridge queries Resident Set Size (RSS) via oc_mem_rss_bytes().
• SIMD and Threads: Configuration flags enable_simd and enable_threads allow the host to toggle hardware features based on browser capabilities.
• Deterministic Stubs: For testing, a built-in stub generator produces predictable token sequences (based on FNV-1a prompt hashing) when no real model is loaded.

Sources: oxidize-c/src/util/wasm_bridge.c:95-115, oxidize-c/src/util/wasm_bridge.c:340-360, oxidize-c/tests/test_wasm.c:200-215

API Reference (C Bridge)

Function	Return Type	Purpose
oc_wasm_bridge_init	OcWasmBridge*	Creates a new bridge instance.
oc_wasm_bridge_generate	size_t	Synchronous generation with optional callback.
oc_wasm_bridge_cancel	OcError	Thread-safe atomic cancellation flag setting.
oc_wasm_bridge_enqueue	OcError	Adds a message to the internal ring buffer.
oc_wasm_bridge_drain_one	OcError	Processes the next queued message.

Sources: oxidize-c/include/oxidize/wasm.h:130-220

The WebAssembly Bridge is a critical component for browser-based deployment, providing the necessary glue between the low-level Rust/C inference kernels and the high-level JavaScript application layer. By leveraging WebWorkers and hardware-specific backends like WebGPU, it achieves near-native performance for local-first LLM workflows.