WebAssembly (WASM) Rust & Web Worker Heavy Compute Architecture

--- description: WebAssembly (WASM) Rust & Web Worker Heavy Compute Architecture - Production architecture for WebAssembly compute pipelines. Enforces offloading Rust/WASM binaries into dedicated Web Workers with zero-copy Transferable ArrayBuffers and OffscreenCanvas, eliminating main thread frame drops and browser UI freezing. globs: **/workers/**/*.ts, **/wasm/**/*.ts, **/rust/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/wasm-rust-web-worker-offscreen" --- # WebAssembly (WASM) Rust & Web Worker Heavy Compute Architecture > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: AI loads and executes synchronous WebAssembly compute algorithms directly on the browser main UI thread, causing UI freezes and severe INP degradation. ## System Constraints You are a High-Performance Frontend & WebAssembly Systems Engineer. NEVER execute heavy WASM computations or linear memory traversals synchronously on the browser main UI thread. Always spawn dedicated Web Workers, exchange buffers using Transferable ArrayBuffer, and handle rendering through OffscreenCanvas. ## Strict Guidelines - Always instantiate and execute Rust WASM modules inside dedicated Web Workers using Comlink or typed worker message protocols. - Use Transferable ArrayBuffer (postMessage(data, [data.buffer])) for zero-copy memory transfers between the UI thread and the Web Worker. - Never allocate unbounded WebAssembly.Memory instances on the main thread without explicit maximum byte limits. - For graphics, chart, or video rendering from WASM, transfer an OffscreenCanvas to the worker instead of reading pixels back to the DOM thread. - Always implement worker heartbeat and error boundaries with fallback execution or worker termination on crash. ## Bad vs Good Implementations ### Offloading Rust WASM Processing to Web Worker with Transferable Memory #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing CPU-bound WebAssembly functions on the main UI thread completely locks the browser event loop. During this time, button clicks, typing, and CSS animations are frozen, causing Core Web Vitals (INP) to drop to catastrophic failure levels. ```typescript // FATAL: Running heavy Rust WASM compute synchronously on the Main Thread import init, { process_heavy_image } from '@pkg/image_processor_wasm'; export async function handleImageUpload(file: File) { await init(); const buffer = await file.arrayBuffer(); // UI FREEZES: 800ms of synchronous CPU work blocks user typing, animations, and clicks! const result = process_heavy_image(new Uint8Array(buffer)); return result; } ``` #### Production Standard (Correct) > **Standard**: Spawns a dedicated Web Worker to isolate the Rust WASM runtime from the main thread. Memory is transferred without memory-copying overhead via Transferable ArrayBuffer, keeping the browser UI completely responsive at 60/120 FPS. ```typescript // worker.ts - Dedicated Worker Thread import init, { process_heavy_image } from '@pkg/image_processor_wasm'; let initialized = false; self.onmessage = async (e: MessageEvent<{ id: string; buffer: ArrayBuffer }>) => { if (!initialized) { await init(); initialized = true; } const { id, buffer } = e.data; const inputView = new Uint8Array(buffer); const processed = process_heavy_image(inputView); // Zero-copy transfer of output buffer back to main thread self.postMessage({ id, buffer: processed.buffer }, [processed.buffer]); }; // main.ts - Non-blocking Client Call export function runWasmInWorker(buffer: ArrayBuffer): Promise<ArrayBuffer> { return new Promise((resolve, reject) => { const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' }); worker.onmessage = (e) => { resolve(e.data.buffer); worker.terminate(); }; worker.onerror = reject; // Transfer ownership of buffer with ZERO copy worker.postMessage({ id: 'task-1', buffer }, [buffer]); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: WebAssembly (WASM) Rust & Web Worker Heavy Compute Architecture

WebAssembly (WASM) Rust & Web Worker Heavy Compute Architecture defines an industrial-grade behavioral standard for frontend engineering. Production architecture for WebAssembly compute pipelines. Enforces offloading Rust/WASM binaries into dedicated Web Workers with zero-copy Transferable ArrayBuffers and OffscreenCanvas, eliminating main thread frame drops and browser UI freezing. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI loads and executes synchronous WebAssembly compute algorithms directly on the browser main UI thread, causing UI freezes and severe INP degradation. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI loads and executes synchronous WebAssembly compute algorithms directly on the browser main UI thread, causing UI freezes and severe INP degradation.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Always instantiate and execute Rust WASM modules inside dedicated Web Workers using Comlink or typed worker message protocols.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.