Intermediate

# Install wasm-pack (includes wasm-bindgen-cli internally)
cargo install wasm-pack              # => installs wasm-pack 0.14.0
 
# Create a new Wasm library project
wasm-pack new wasm-greet             # => scaffolds project structure
# => creates wasm-greet/
# =>   src/lib.rs         — Rust source with example code
# =>   Cargo.toml         — with wasm-bindgen dependency
# =>   tests/web.rs       — browser integration tests
 
cd wasm-greet

# Cargo.toml — required configuration for Wasm library
[package]
name = "wasm-greet"
version = "0.1.0"
edition = "2021"
 
[lib]
# cdylib: C-compatible dynamic library (required for Wasm loading)
# rlib: Rust library (optional, for use by other Rust crates)
crate-type = ["cdylib", "rlib"]
 
[dependencies]
# CRITICAL: version must exactly match wasm-bindgen-cli version
wasm-bindgen = "0.2.120"   # => provides #[wasm_bindgen] attribute macro
 
[dev-dependencies]
wasm-bindgen-test = "0.3"  # => browser-based testing framework

# Build for browser target (ESM module output)
wasm-pack build --target web         # => produces pkg/ directory:
                                      # => pkg/wasm_greet_bg.wasm    — binary
                                      # => pkg/wasm_greet.js         — JS bindings
                                      # => pkg/wasm_greet.d.ts       — TypeScript types
                                      # => pkg/package.json          — npm package manifest
 
# Build for bundler (Webpack/Vite/esbuild): uses import statements
wasm-pack build --target bundler     # => adds "type": "module" to package.json
 
# Build for Node.js (CommonJS): uses require()
wasm-pack build --target nodejs      # => CommonJS output with require()

// src/lib.rs — #[wasm_bindgen] on functions
use wasm_bindgen::prelude::*;   // => import wasm_bindgen macros and types
 
// Export a simple function: JS calls add(3, 4), gets back 7
#[wasm_bindgen]
pub fn add(a: i32, b: i32) -> i32 {
    a + b     // => i32 addition; maps directly to Wasm i32.add
               // => no wrappers needed: i32 is a Wasm native type
}
 
// Export a function with a renamed JS name
#[wasm_bindgen(js_name = "greet")]  // => exported as "greet" not "hello_world"
pub fn hello_world() -> String {
    "Hello from Rust!".to_string()  // => String needs copying across boundary
                                     // => wasm-bindgen handles ptr+len allocation
}
 
// Export a function that can panic (panic hook converts to JS Error)
#[wasm_bindgen]
pub fn divide(a: f64, b: f64) -> f64 {
    if b == 0.0 {
        panic!("division by zero");  // => with console_error_panic_hook: logs to console
                                      // => without: cryptic "unreachable executed" error
    }
    a / b
}
 
// Initialize the panic hook (call this once at startup)
#[wasm_bindgen(start)]             // => runs this function when module instantiates
pub fn init() {
    console_error_panic_hook::set_once(); // => converts Rust panics to JS console.error
}

// usage.js — calling wasm-bindgen exported functions
import init, { add, greet, divide } from "./pkg/wasm_greet.js";
 
await init(); // => fetches and instantiates the .wasm binary
 
console.log(add(3, 4)); // => 7
console.log(greet()); // => "Hello from Rust!"
 
try {
  divide(10, 0); // => triggers Rust panic
} catch (e) {
  console.error(e.message); // => "panicked at 'division by zero', src/lib.rs:15:9"
}

// src/lib.rs — string passing with wasm-bindgen 0.2.120
use wasm_bindgen::prelude::*;
 
// Rust → JS: returning a String allocates on Wasm heap, copies to JS string
#[wasm_bindgen]
pub fn make_greeting(name: &str) -> String {  // => &str: borrowed from JS
    format!("Hello, {}! From Rust.", name)    // => format! creates new String
                                               // => wasm-bindgen: alloc in Wasm, copy to JS, free
}
 
// JS → Rust: accepting &str borrows JS string's UTF-8 encoding
#[wasm_bindgen]
pub fn count_chars(s: &str) -> usize {
    s.chars().count()   // => counts Unicode scalar values (not bytes)
                         // => "café" → 4 (4 chars) but 5 bytes in UTF-8
}
 
// Accepting String: moves ownership into Rust
#[wasm_bindgen]
pub fn to_uppercase(s: String) -> String {
    s.to_uppercase()    // => consumes s, returns new String
                         // => UTF-8 aware: handles non-ASCII correctly
}
 
// Returning Option<String>: None becomes null/undefined in JS
#[wasm_bindgen]
pub fn parse_int(s: &str) -> Option<i32> {
    s.parse::<i32>().ok()  // => Ok(n) → Some(n) → n in JS
                             // => Err(_) → None → undefined in JS
}

// string-usage.js
import init, { make_greeting, count_chars, to_uppercase, parse_int } from "./pkg/wasm_greet.js";
await init();
 
console.log(make_greeting("World")); // => "Hello, World! From Rust."
console.log(count_chars("café")); // => 4 (Unicode chars, not bytes)
console.log(to_uppercase("hello")); // => "HELLO"
console.log(parse_int("42")); // => 42
console.log(parse_int("not-a-number")); // => undefined (None → undefined)

// src/lib.rs — byte slice passing
use wasm_bindgen::prelude::*;
use js_sys::Uint8Array;
 
// Accept &[u8]: wasm-bindgen copies JS Uint8Array into Wasm memory
#[wasm_bindgen]
pub fn sum_bytes(data: &[u8]) -> u32 {
    data.iter().map(|&b| b as u32).sum()  // => sum all bytes as u32
                                            // => data is a Rust slice into Wasm memory
}
 
// Return Vec<u8>: wasm-bindgen copies Wasm bytes to a new JS Uint8Array
#[wasm_bindgen]
pub fn reverse_bytes(data: &[u8]) -> Vec<u8> {
    let mut result = data.to_vec();  // => copy: &[u8] → Vec<u8>
    result.reverse();                // => reverse in place
    result                           // => wasm-bindgen: alloc JS Uint8Array, copy bytes
}
 
// Zero-copy with js_sys::Uint8Array: operate on JS memory directly
#[wasm_bindgen]
pub fn invert_colors(input: &Uint8Array, output: &Uint8Array) {
    // Zero-copy read from JS typed array (unsafe: borrows JS memory)
    let len = input.length() as usize;  // => byte length of input
    for i in 0..len {
        // Invert each byte (255 - byte inverts the color channel)
        output.set_index(i as u32, 255 - input.get_index(i as u32));
    }
    // => No heap allocation needed — operates directly on JS Uint8Array memory
}

// byte-slice-usage.js
import init, { sum_bytes, reverse_bytes, invert_colors } from "./pkg/wasm_greet.js";
await init();
 
const data = new Uint8Array([10, 20, 30, 40, 50]);
 
console.log(sum_bytes(data)); // => 150
console.log(reverse_bytes(data)); // => Uint8Array [50, 40, 30, 20, 10]
 
// Zero-copy color inversion
const pixels = new Uint8Array([255, 128, 0, 255]); // => RGBA: opaque orange
const inverted = new Uint8Array(4);
invert_colors(pixels, inverted);
console.log([...inverted]); // => [0, 127, 255, 0] — inverted channels

// src/lib.rs — exporting a Rust struct as a JS class
use wasm_bindgen::prelude::*;
 
#[wasm_bindgen]
pub struct Counter {
    value: i32,    // => private field (no wasm_bindgen on field)
    step: i32,     // => increment step
}
 
#[wasm_bindgen]
impl Counter {
    // Constructor: JS calls `new Counter(step)`
    #[wasm_bindgen(constructor)]
    pub fn new(step: i32) -> Counter {
        Counter { value: 0, step }  // => creates Counter on Wasm heap
    }
 
    // Instance method: JS calls `counter.increment()`
    pub fn increment(&mut self) {
        self.value += self.step;    // => mutates Wasm-side state
    }
 
    // Getter: JS calls `counter.value` (not counter.value())
    #[wasm_bindgen(getter)]
    pub fn value(&self) -> i32 {
        self.value  // => reads Wasm-side field
    }
 
    // Static method: JS calls `Counter.reset()`
    pub fn reset_all() {
        // => static method: no `self`, no instance needed
        web_sys::console::log_1(&"All counters conceptually reset".into());
    }
}
 
// Drop is automatic: when JS GC collects the handle, Wasm memory is freed
// (in wasm-bindgen 0.2.x, explicit .free() is available for deterministic drop)

// class-usage.js
import init, { Counter } from "./pkg/wasm_greet.js";
await init();
 
const counter = new Counter(5); // => calls Counter::new(5)
// => counter.value is 0
console.log(counter.value); // => 0 (getter property)
 
counter.increment(); // => counter.value is now 5
counter.increment(); // => counter.value is now 10
console.log(counter.value); // => 10
 
Counter.reset_all(); // => static method call
counter.free(); // => explicit drop (optional; GC also collects)

# Cargo.toml — enabling web-sys features
[dependencies]
wasm-bindgen = "0.2.120"
web-sys = { version = "0.3", features = [
  "Window",         # => window.document, window.location, etc.
  "Document",       # => document.getElementById, document.createElement, etc.
  "HtmlCanvasElement", # => canvas.getContext("2d")
  "CanvasRenderingContext2d", # => ctx.fillRect, ctx.drawImage, etc.
  "console",        # => console.log from Rust
]}

// src/lib.rs — using web-sys to call browser APIs from Rust
use wasm_bindgen::prelude::*;
use web_sys::{window, HtmlCanvasElement, CanvasRenderingContext2d};
 
#[wasm_bindgen]
pub fn draw_rect(canvas_id: &str, x: f64, y: f64, w: f64, h: f64, color: &str) {
    let document = window()             // => web_sys::window() → Option<Window>
        .unwrap()                       // => panics if not in browser context
        .document()                     // => → Option<Document>
        .unwrap();
 
    let canvas = document
        .get_element_by_id(canvas_id)  // => → Option<Element>
        .unwrap()
        .dyn_into::<HtmlCanvasElement>() // => cast Element to HtmlCanvasElement
        .map_err(|_| "canvas not found")
        .unwrap();
 
    let ctx = canvas
        .get_context("2d")             // => → Result<Option<Object>, JsValue>
        .unwrap()
        .unwrap()
        .dyn_into::<CanvasRenderingContext2d>() // => cast to canvas 2D context
        .unwrap();
 
    ctx.set_fill_style(&color.into()); // => ctx.fillStyle = color
    ctx.fill_rect(x, y, w, h);        // => ctx.fillRect(x, y, w, h)
}
 
// Log to browser console from Rust
#[wasm_bindgen]
pub fn log_message(msg: &str) {
    web_sys::console::log_1(&msg.into()); // => console.log(msg) from Rust
}

// src/lib.rs — calling JS from Rust via js_sys and extern blocks
use wasm_bindgen::prelude::*;
use js_sys::{Math, Date, Array};
 
// Use js_sys built-ins directly from Rust
#[wasm_bindgen]
pub fn random_between(min: f64, max: f64) -> f64 {
    min + (max - min) * Math::random() // => calls JavaScript Math.random()
                                         // => result: uniformly distributed in [min, max)
}
 
#[wasm_bindgen]
pub fn current_timestamp() -> f64 {
    Date::now()   // => calls JavaScript Date.now()
                   // => returns milliseconds since Unix epoch as f64
}
 
// Import a custom JS function using extern block
#[wasm_bindgen]
extern "C" {
    // This function must be provided in the importObject or as a global
    fn alert(s: &str);                      // => window.alert from Rust
    fn custom_callback(value: i32) -> bool; // => custom JS function
}
 
#[wasm_bindgen]
pub fn notify_user(msg: &str) {
    alert(msg);   // => calls window.alert(msg)
}
 
// Create JS arrays from Rust
#[wasm_bindgen]
pub fn make_js_array(n: u32) -> Array {
    let arr = Array::new_with_length(n);    // => new Array(n)
    for i in 0..n {
        arr.set(i, JsValue::from(i * i));   // => arr[i] = i*i
    }
    arr  // => returns JS Array to JavaScript caller
}

# Target: web — ESM with inline init() function
# Use with: Vite, static HTML, no bundler needed
wasm-pack build --target web
# => pkg/wasm_greet.js uses:
# =>   import * as wasm from './wasm_greet_bg.wasm?url';
# =>   export async function init() { ... }
# => Consumer: import init, { add } from './pkg/wasm_greet.js'; await init();
 
# Target: bundler — ESM with bundler-processed Wasm import
# Use with: Webpack 5 (syncWebAssembly/asyncWebAssembly), Rollup, esbuild
wasm-pack build --target bundler
# => pkg/wasm_greet.js uses:
# =>   import * as wasm from './wasm_greet_bg.wasm';
# =>   export { add }; // no init() needed — bundler handles instantiation
# => Consumer: import { add } from './pkg/wasm_greet.js'; add(1, 2);
 
# Target: nodejs — CommonJS for Node.js
# Use with: Node.js scripts, Jest, server-side rendering
wasm-pack build --target nodejs
# => pkg/wasm_greet.js uses:
# =>   const wasm = require('./wasm_greet_bg');
# =>   const { add } = require('./pkg/wasm_greet.js');
 
# Target: no-modules — global variable (legacy, browser only)
# Use with: old-school <script> tags, no bundler, no ESM
wasm-pack build --target no-modules
# => pkg/wasm_greet.js sets window.wasm_greet = { add, ... }
# => <script src="pkg/wasm_greet.js"></script>
 
# Add --release for optimized build (default is debug with assertions)
wasm-pack build --target web --release
# => smaller binary, no debug assertions, better performance

// vite-usage.js — Vite integration (Vite 5+)
// Vite can load .wasm files directly using the ?init query
// Requires: vite.config.ts with no special plugin for basic usage
 
// Option 1: ?init suffix — Vite provides instantiation wrapper
import initWasm from "./pkg/wasm_greet_bg.wasm?init";
// => Vite handles fetch + instantiation
const instance = await initWasm({
  "./wasm_greet_bg.js": (await import("./pkg/wasm_greet.js")).default,
});
 
// Option 2: wasm-pack --target web with Vite (recommended)
import init, { add } from "./pkg/wasm_greet.js"; // => ESM import
await init(); // => fetches wasm_greet_bg.wasm relative to wasm_greet.js
console.log(add(3, 4)); // => 7

// next-usage.js — Next.js App Router (Next.js 14+)
// next.config.ts must enable asyncWebAssembly experiment:
// const nextConfig = { experimental: { asyncWebAssembly: true } };
// module.exports = nextConfig;
 
// In a Server Component or API Route:
// Import the JS bindings (Next.js bundler handles the .wasm file)
import init, { add } from "@/lib/wasm/wasm_greet.js"; // => placed in lib/wasm/
 
export async function GET() {
  await init(); // => loads .wasm from static assets
  const result = add(10, 20); // => 30
  return Response.json({ result });
}

// next.config.ts — required Next.js Wasm configuration
import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  experimental: {
    asyncWebAssembly: true, // => enables Wasm module imports
  },
};
 
export default nextConfig;

# Cargo.toml — async dependencies
[dependencies]
wasm-bindgen = "0.2.120"
wasm-bindgen-futures = "0.4"    # => Future ↔ Promise bridge
js-sys = "0.3"                   # => JavaScript built-ins
web-sys = { version = "0.3", features = ["Window", "Request", "Response", "Headers"] }

// src/lib.rs — async Wasm with wasm-bindgen-futures
use wasm_bindgen::prelude::*;
use wasm_bindgen_futures::JsFuture;  // => converts JS Promise to Rust Future
use web_sys::{Request, Response};
 
// async fn exported as returning a Promise in JS
#[wasm_bindgen]
pub async fn fetch_text(url: String) -> Result<String, JsValue> {
    let window = web_sys::window().unwrap();
 
    // window.fetch() returns a JS Promise
    let resp_value = JsFuture::from(window.fetch_with_str(&url))
        .await                          // => awaits the JS fetch() Promise
        .map_err(|e| e)?;              // => propagate JS errors as JsValue
 
    let resp: Response = resp_value.dyn_into()?; // => cast to Response
 
    // resp.text() returns another JS Promise
    let text = JsFuture::from(resp.text()?)
        .await?                         // => awaits text() Promise
        .as_string()                    // => JsValue → Option<String>
        .ok_or_else(|| "not a string".into())?;
 
    Ok(text) // => returned as resolved JS Promise value
}
 
// spawn_local: run an async task without awaiting (fire-and-forget)
#[wasm_bindgen]
pub fn start_background_task() {
    wasm_bindgen_futures::spawn_local(async {
        let result = fetch_text("https://api.example.com/data".into()).await;
        match result {
            Ok(text) => web_sys::console::log_1(&text.into()),
            Err(e) => web_sys::console::error_1(&e),
        }
    });
}

// async-usage.js
import init, { fetch_text, start_background_task } from "./pkg/wasm_greet.js";
await init();
 
// async Rust fn exports as async JS fn (returns Promise)
const text = await fetch_text("https://httpbin.org/get");
console.log(text); // => JSON response body as string
 
start_background_task(); // => fires async task without awaiting

# Install Emscripten (using emsdk)
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install 5.0.6               # => downloads and installs Emscripten 5.0.6
./emsdk activate 5.0.6              # => sets up PATH for this version
source ./emsdk_env.sh               # => activates in current shell
 
emcc --version                      # => emcc (Emscripten gcc/clang-like replacement)...
                                     # => version: 5.0.6

// hello.c — basic C hello world for Emscripten compilation
#include <stdio.h>
 
int main() {
    printf("Hello from C via WebAssembly!\n");  // => standard C printf
    return 0;                                    // => exit code 0
}

# Compile C to WebAssembly + HTML (full standalone demo)
emcc hello.c -o hello.html
# => produces 3 files:
# => hello.html  — browser wrapper with Emscripten JS runtime
# => hello.js    — Emscripten runtime + module loader
# => hello.wasm  — the WebAssembly binary
 
# Serve and open (Emscripten HTML requires a server, not file://)
npx serve .                         # => serves on http://localhost:3000
# open http://localhost:3000/hello.html
# => browser runs C main(), printf output appears in JS console + emterm
 
# Compile to just .wasm + .js (no HTML wrapper)
emcc hello.c -o hello.js
# => hello.js    — CommonJS module (can be required in Node.js)
# => hello.wasm  — Wasm binary
 
# Run with Node.js (requires Node.js 18.3.0+)
node hello.js
# => Output: Hello from C via WebAssembly!

// math-exports.c — exporting C functions via Emscripten
#include <emscripten.h>  // => provides EMSCRIPTEN_KEEPALIVE, EM_JS, EM_ASM
 
// EMSCRIPTEN_KEEPALIVE: prevents compiler from eliminating this function
// as dead code, and marks it for export to JS
EMSCRIPTEN_KEEPALIVE
int add(int a, int b) {
    return a + b;    // => basic C integer addition
}
 
EMSCRIPTEN_KEEPALIVE
double power(double base, double exp) {
    double result = 1.0;
    for (int i = 0; i < (int)exp; i++) {
        result *= base;  // => naive power (for demonstration)
    }
    return result;
}
 
// EM_JS: embed JavaScript directly in C source
// Called like a normal C function but executes JavaScript
EM_JS(void, log_from_c, (const char* msg), {
    // This is JavaScript code — runs when C calls log_from_c(str)
    console.log("C says: " + UTF8ToString(msg));  // => UTF8ToString converts ptr to JS string
})
 
int main() {
    log_from_c("main() called");  // => calls the EM_JS JavaScript
    return 0;
}

# Compile with explicit exported functions
emcc math-exports.c -o math.js \
  -s EXPORTED_FUNCTIONS='["_add", "_power", "_main"]' \
  -s EXPORTED_RUNTIME_METHODS='["ccall", "cwrap"]'
# => _add and _power are prefixed with _ in the Wasm export table
# => EXPORTED_RUNTIME_METHODS exposes ccall/cwrap for easier calling
 
# Run in Node.js
node -e "
const Module = require('./math.js');
Module.onRuntimeInitialized = () => {
  const add = Module.cwrap('add', 'number', ['number', 'number']);
  console.log(add(3, 4)); // => 7
};
"

// js-from-c.c — different ways to call JS from C with Emscripten
#include <emscripten.h>
#include <stdio.h>
 
// EM_JS: define a JS function callable from C
// Syntax: EM_JS(return_type, function_name, (params), { js_body })
EM_JS(int, js_add, (int a, int b), {
    return a + b;    // => this JavaScript runs when C calls js_add(a, b)
                      // => a and b are automatically converted from C int to JS number
});
 
// EM_JS with string parameter: uses Emscripten's UTF8ToString helper
EM_JS(void, js_alert, (const char* msg), {
    alert(UTF8ToString(msg));  // => UTF8ToString converts C string pointer to JS string
                                // => alert(msg) shows browser alert dialog
});
 
// EM_JS returning a double
EM_JS(double, js_sqrt, (double x), {
    return Math.sqrt(x);  // => calls JavaScript Math.sqrt
});
 
int main() {
    int sum = js_add(10, 20);            // => calls embedded JS: returns 30
    printf("js_add(10, 20) = %d\n", sum); // => Output: js_add(10, 20) = 30
 
    double root = js_sqrt(2.0);           // => Math.sqrt(2.0)
    printf("sqrt(2) = %f\n", root);       // => Output: sqrt(2) = 1.414214
 
    // EM_ASM: inline JS expression (no return value, no name)
    EM_ASM({
        console.log("Inline JS from C: " + $0);  // => $0 is first arg
    }, 42);  // => Output: Inline JS from C: 42
 
    // emscripten_run_script: eval a string (slow, for debugging only)
    emscripten_run_script("console.log('run_script called')");
    // => Output: run_script called
 
    return 0;
}

// buffers.c — malloc/free with cross-boundary buffer passing
#include <stdlib.h>
#include <string.h>
#include <emscripten.h>
 
// Process a byte array in-place (invert each byte)
EMSCRIPTEN_KEEPALIVE
void invert_bytes(uint8_t* data, int len) {
    for (int i = 0; i < len; i++) {
        data[i] = 255 - data[i];   // => invert each byte in-place
    }
}
 
// Return a newly malloc'd buffer (caller must free!)
EMSCRIPTEN_KEEPALIVE
uint8_t* create_pattern(int size) {
    uint8_t* buf = (uint8_t*)malloc(size);  // => allocate on C heap
    for (int i = 0; i < size; i++) {
        buf[i] = (uint8_t)(i % 256);        // => fill with 0,1,2,...,255,0,1,...
    }
    return buf;   // => return pointer (JS must read, then free)
}

// malloc-usage.js — JavaScript side of malloc/free pattern
const Module = await require("./buffers.js");
 
// Wait for Emscripten runtime to initialize
await new Promise((resolve) => {
  Module.onRuntimeInitialized = resolve;
});
 
// Allocate memory in C heap, write from JS, process in C
const size = 1024;
const ptr = Module._malloc(size); // => allocate 1024 bytes in C heap
const heapBytes = new Uint8Array(Module.HEAPU8.buffer, ptr, size);
// => HEAPU8 is Emscripten's Uint8Array view over C heap
 
for (let i = 0; i < size; i++) {
  heapBytes[i] = i % 256; // => fill from JS side
}
 
Module._invert_bytes(ptr, size); // => C function inverts in-place
 
// Read results back
console.log([...heapBytes.slice(0, 4)]); // => [255, 254, 253, 252]
 
Module._free(ptr); // => CRITICAL: free C heap allocation
// => forgetting this leaks C heap memory
 
// Get a malloc'd buffer from C, read it, then free
const bufPtr = Module._create_pattern(256);
const buf = new Uint8Array(Module.HEAPU8.buffer, bufPtr, 256);
console.log([...buf.slice(0, 5)]); // => [0, 1, 2, 3, 4]
Module._free(bufPtr); // => free the C-allocated buffer

// grayscale.c — grayscale conversion in C for Emscripten
#include <stdint.h>
#include <emscripten.h>
 
// Convert RGBA image to grayscale in-place
// data: pointer to RGBA pixel buffer (4 bytes per pixel)
// len: total number of bytes (width * height * 4)
EMSCRIPTEN_KEEPALIVE
void to_grayscale(uint8_t* data, int len) {
    for (int i = 0; i < len; i += 4) {
        // Standard luminance formula: Y = 0.299R + 0.587G + 0.114B
        uint8_t r = data[i];        // => red channel
        uint8_t g = data[i + 1];    // => green channel
        uint8_t b = data[i + 2];    // => blue channel
        // data[i + 3] is alpha — leave unchanged
 
        uint8_t gray = (uint8_t)(0.299 * r + 0.587 * g + 0.114 * b);
        // => weighted average: green contributes most to perceived brightness
 
        data[i]     = gray;  // => overwrite R with gray
        data[i + 1] = gray;  // => overwrite G with gray
        data[i + 2] = gray;  // => overwrite B with gray
        // data[i + 3] unchanged (preserve alpha)
    }
}

// grayscale-usage.js — Canvas API + Emscripten grayscale
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
 
// Draw an image onto canvas first
const img = document.getElementById("source-image");
ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
 
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
const pixels = imageData.data; // => Uint8ClampedArray: RGBA bytes
const byteLen = pixels.length; // => width * height * 4
 
// Wait for Emscripten Module to load
const Module = await loadEmscriptenModule("./grayscale.js");
 
// Allocate C heap buffer, copy pixels in
const ptr = Module._malloc(byteLen);
Module.HEAPU8.set(pixels, ptr); // => copy from Canvas to C heap
 
// Run the C grayscale function (processes in-place in C heap)
Module._to_grayscale(ptr, byteLen); // => pure C computation
 
// Copy processed pixels back to Canvas ImageData
pixels.set(Module.HEAPU8.subarray(ptr, ptr + byteLen)); // => copy back
Module._free(ptr); // => release C heap allocation
 
// Put modified image data back onto canvas
ctx.putImageData(imageData, 0, 0); // => display grayscale image

# Compile with memory growth enabled
emcc large-processor.c -o large.js \
  -s ALLOW_MEMORY_GROWTH=1 \
  -s INITIAL_MEMORY=16MB \
  -s MAXIMUM_MEMORY=512MB \
  -s EXPORTED_FUNCTIONS='["_process_large_data", "_malloc", "_free"]'
# => INITIAL_MEMORY: start with 16 MB
# => MAXIMUM_MEMORY: allow growth up to 512 MB
# => ALLOW_MEMORY_GROWTH=1: malloc calls memory.grow when needed
 
# Without ALLOW_MEMORY_GROWTH (default):
emcc large-processor.c -o fixed.js \
  -s INITIAL_MEMORY=64MB
# => fixed 64 MB heap: malloc returns NULL if heap is exhausted
# => no automatic growth
 
# Performance trade-off: ALLOW_MEMORY_GROWTH=1 disables some optimizations
# because the runtime must handle variable-length memory
# For performance-critical code with known max memory, prefer fixed initial

// large-processor.c — dynamic memory growth scenario
#include <stdlib.h>
#include <emscripten.h>
 
EMSCRIPTEN_KEEPALIVE
int process_large_data(int size_bytes) {
    // With ALLOW_MEMORY_GROWTH=1: malloc triggers memory.grow if needed
    uint8_t* buf = (uint8_t*)malloc(size_bytes);
    if (!buf) return -1;  // => NULL on OOM even with growth (if max exceeded)
 
    // Process the data...
    for (int i = 0; i < size_bytes; i++) {
        buf[i] = (uint8_t)(i % 256);  // => fill pattern
    }
 
    free(buf);   // => release allocation
    return 0;    // => success
}

// boundary-optimization.js — batching vs chatty calls
 
// BAD: chatty pattern — one call per pixel (millions of boundary crossings)
async function processPixelsBad(imageData) {
  const { instance } = await WebAssembly.instantiateStreaming(fetch("/wasm/proc.wasm"));
  const pixels = imageData.data;
 
  for (let i = 0; i < pixels.length; i += 4) {
    // Each call is a boundary crossing with argument marshalling
    pixels[i] = instance.exports.processRed(pixels[i]); // => boundary crossing!
    pixels[i + 1] = instance.exports.processGreen(pixels[i + 1]); // => boundary crossing!
    pixels[i + 2] = instance.exports.processBlue(pixels[i + 2]); // => boundary crossing!
    // => 3 * (width*height) crossings for a full image = millions of crossings
  }
}
 
// GOOD: batch pattern — one call for the entire image
async function processPixelsGood(imageData) {
  const { instance } = await WebAssembly.instantiateStreaming(fetch("/wasm/proc.wasm"));
  const memory = instance.exports.memory;
  const pixels = imageData.data;
 
  // Allocate a region in Wasm memory for the pixel data
  const ptr = instance.exports.alloc(pixels.length); // => one call to allocate
  new Uint8Array(memory.buffer).set(pixels, ptr); // => one TypedArray bulk copy
 
  instance.exports.processAllPixels(ptr, pixels.length); // => ONE boundary crossing
  // => entire image processed in Wasm
 
  // Read results back (one bulk copy)
  pixels.set(new Uint8Array(memory.buffer, ptr, pixels.length));
  instance.exports.dealloc(ptr, pixels.length); // => one call to free
  // => 4 crossings total vs 3 * width * height crossings
}

// main.js — main thread: share memory with worker
const sharedMemory = new WebAssembly.Memory({
  initial: 4, // => 4 * 64KiB = 256 KiB shared
  maximum: 16, // => max 1 MiB
  shared: true, // => SharedArrayBuffer backing (requires COOP/COEP headers)
});
 
// Verify SharedArrayBuffer is available (blocked without COOP/COEP)
if (!(sharedMemory.buffer instanceof SharedArrayBuffer)) {
  throw new Error("SharedArrayBuffer unavailable: check COOP/COEP headers");
}
 
const worker = new Worker("./worker.js", { type: "module" });
 
// Transfer the Wasm module (compiled once, shared) and the shared memory
// postMessage with Transferable objects: zero-copy transfer of the Module
const response = await fetch("/wasm/compute.wasm");
const buffer = await response.arrayBuffer();
const module = await WebAssembly.compile(buffer); // => compile on main thread
 
// Send both module and shared memory to worker
// module is structured-cloneable (copied by value — it's stateless)
// sharedMemory.buffer is SharedArrayBuffer (truly shared — no copy)
worker.postMessage({ module, sharedMemory });
 
// Coordinate via Atomics on a control region of shared memory
const control = new Int32Array(sharedMemory.buffer);
Atomics.store(control, 0, 1); // => signal worker to start processing
Atomics.notify(control, 0, 1); // => wake up waiting worker

// worker.js — Web Worker receiving shared memory
self.onmessage = async ({ data: { module, sharedMemory } }) => {
  const instance = await WebAssembly.instantiate(module, {
    env: { memory: sharedMemory }, // => worker uses the SAME backing buffer
  });
 
  const control = new Int32Array(sharedMemory.buffer);
  Atomics.wait(control, 0, 0); // => block until control[0] != 0 (main signals start)
 
  instance.exports.computeHeavyWork(); // => runs in worker thread, writes to shared memory
  // => main thread can read results from sharedMemory.buffer without copying
};

// wasm-worker.js — the worker script
let wasmInstance = null;
 
// Initialize: receive module + import object from main thread
self.onmessage = async ({ data }) => {
  if (data.type === "init") {
    // Instantiate the pre-compiled module (cheap)
    const { instance } = await WebAssembly.instantiate(data.module, {});
    wasmInstance = instance; // => cache the instance
    self.postMessage({ type: "ready" }); // => notify main thread
    return;
  }
 
  if (data.type === "compute" && wasmInstance) {
    const { input, jobId } = data;
    // Run computation in worker (doesn't block UI thread)
    const result = wasmInstance.exports.heavyCompute(input); // => computation
    self.postMessage({ type: "result", jobId, result }); // => send result back
    return;
  }
};

// main.js — main thread: load Wasm in worker
const worker = new Worker("./wasm-worker.js", { type: "module" });
 
// Compile module once on main thread
const module = await WebAssembly.compileStreaming(fetch("/wasm/compute.wasm"));
 
// Send compiled module to worker (structured clone — module is serializable)
worker.postMessage({ type: "init", module });
 
// Wait for worker to be ready
await new Promise((resolve) => {
  worker.onmessage = ({ data }) => {
    if (data.type === "ready") resolve();
  };
});
 
// Submit jobs asynchronously
let jobId = 0;
function compute(input) {
  return new Promise((resolve) => {
    const id = ++jobId;
    worker.postMessage({ type: "compute", input, jobId: id });
    worker.addEventListener("message", function handler({ data }) {
      if (data.type === "result" && data.jobId === id) {
        worker.removeEventListener("message", handler);
        resolve(data.result); // => resolve with computation result
      }
    });
  });
}
 
console.log(await compute(42)); // => result from Wasm in worker

# Install Binaryen (provides wasm-opt)
brew install binaryen               # => installs wasm-opt, wasm-dis, wasm-merge, etc.
wasm-opt --version                  # => wasm-opt version_129
 
# Basic optimization: -O3 (maximize performance)
wasm-opt -O3 -o optimized.wasm input.wasm
# => applies optimization passes: inlining, DCE, constant propagation, etc.
# => typical size reduction: 10-20% for simple modules
# => may also improve execution speed (removes dead code, enables inlining)
 
# Optimize for size: -Oz (minimize binary size)
wasm-opt -Oz -o small.wasm input.wasm
# => prioritizes size reduction over speed
# => typical additional reduction: 5-15% vs -O3
# => useful for download-size-critical applications
 
# Balanced: -O2 (good balance of size and speed)
wasm-opt -O2 -o balanced.wasm input.wasm
 
# Specific passes: run only named optimization passes
wasm-opt --dce --inlining --const-hoisting -o custom.wasm input.wasm
# => DCE: dead code elimination
# => inlining: inline small functions
# => const-hoisting: hoist constants out of loops
 
# Check size reduction
ls -lh input.wasm optimized.wasm
# => input.wasm:     1.2M
# => optimized.wasm: 980K   (18% reduction — typical range: 10-20%)
 
# wasm-pack integrates wasm-opt automatically in --release builds
wasm-pack build --target web --release
# => runs wasm-opt internally after wasm-bindgen processing

// benchmark.js — measuring Wasm function performance
 
const { instance } = await WebAssembly.instantiateStreaming(fetch("/wasm/compute.wasm"));
 
const { fibonacci, sum_range } = instance.exports;
 
function benchmark(fn, label, iterations = 1000) {
  // Warm-up: allow JIT to tier up from Liftoff to TurboFan (V8)
  for (let i = 0; i < 10; i++) fn(); // => 10 warm-up runs
  // => Wasm JIT promotes hot functions to optimized tier
 
  // Measure
  const start = performance.now(); // => high-resolution timestamp (ms)
  for (let i = 0; i < iterations; i++) {
    fn(); // => measured iteration
  }
  const end = performance.now(); // => end timestamp
 
  const totalMs = end - start; // => total time in milliseconds
  const avgUs = (totalMs * 1000) / iterations; // => average in microseconds
  console.log(`${label}: ${avgUs.toFixed(2)}μs per call (${iterations} iters)`);
}
 
// Benchmark fib(30) — recursive exponential
benchmark(() => fibonacci(30), "fib(30)");
// => fib(30): ~8.20μs per call (1000 iters)  [values vary by machine]
 
// Benchmark sum_range(1, 1000000) — linear loop
benchmark(() => sum_range(1, 1_000_000), "sum(1..1M)");
// => sum(1..1M): ~120.50μs per call (1000 iters)
 
// Compare Wasm vs JavaScript equivalent
function jsFib(n) {
  if (n < 2) return n;
  return jsFib(n - 1) + jsFib(n - 2);
}
benchmark(() => jsFib(30), "JS fib(30)");
// => JS fib(30): ~9.10μs per call  (often close to Wasm for simple recursion)
// => Note: for larger inputs or SIMD, Wasm advantage grows significantly

// compilation-comparison.js — streaming vs buffer-based compilation
 
// Method 1: Streaming (recommended for browser, fast connections + slow connections)
async function loadStreaming(url) {
  const start = performance.now();
  const { instance } = await WebAssembly.instantiateStreaming(
    fetch(url), // => compilation starts as bytes arrive
    {},
  );
  console.log(`Streaming: ${(performance.now() - start).toFixed(1)}ms`);
  return instance;
}
 
// Method 2: Buffer-based (required when Content-Type is wrong or in Node.js)
async function loadFromBuffer(url) {
  const start = performance.now();
  const buffer = await fetch(url).then((r) => r.arrayBuffer()); // => full download first
  const { instance } = await WebAssembly.instantiate(buffer, {});
  // => compilation starts AFTER full download
  console.log(`Buffer: ${(performance.now() - start).toFixed(1)}ms`);
  return instance;
}
 
// Streaming advantage grows with file size
// Small module (50 KB): streaming ~20ms, buffer ~22ms (negligible difference)
// Large module (5 MB): streaming ~400ms, buffer ~600ms (streaming 33% faster)
 
// When to use each:
// instantiateStreaming: browser + correct Content-Type header (application/wasm)
// instantiate(buffer): Node.js, incorrect Content-Type, need to modify binary
 
// Detect and use best available method
async function loadBest(url, imports = {}) {
  if (typeof WebAssembly.instantiateStreaming === "function") {
    try {
      return await WebAssembly.instantiateStreaming(fetch(url), imports);
    } catch (e) {
      // Fallback if Content-Type is wrong (common with some hosting providers)
      console.warn("Streaming failed, falling back to buffer:", e.message);
    }
  }
  const buffer = await fetch(url).then((r) => r.arrayBuffer());
  return WebAssembly.instantiate(buffer, imports);
}

# Add the WASI target (NOT wasm32-wasi — that was removed in Rust 1.84!)
rustup target add wasm32-wasip1         # => installs wasm32-wasip1 target
                                          # => CRITICAL: wasm32-wasi is REMOVED (Rust 1.84+)

// src/main.rs — WASI Hello World (standard Rust binary, not a library)
// Note: this is main.rs (binary), not lib.rs
// No wasm-bindgen needed for WASI — uses standard Rust std
 
fn main() {
    // Standard Rust I/O works via WASI system calls
    println!("Hello from WASI!");    // => writes to WASI stdout fd (fd=1)
                                      // => runtime maps fd to host stdout
 
    // Standard file operations work via preopened directories
    // (see Example 53 for file I/O)
 
    // Environment variable access
    let path = std::env::var("PATH").unwrap_or_else(|_| "not set".to_string());
    // => WASI runtime provides env vars (or empty set)
    println!("PATH: {}", path);       // => Output: PATH: not set (unless runtime provides it)
}

# Compile to WASI binary
cargo build --target wasm32-wasip1   # => compiles for WASI target
# => produces: target/wasm32-wasip1/debug/hello-wasi.wasm
 
# Cargo.toml for a WASI binary (not a library — no cdylib)
# [package]
# name = "hello-wasi"
# edition = "2021"
# No [lib] section — this is a binary with main()
 
# Build release
cargo build --target wasm32-wasip1 --release
# => target/wasm32-wasip1/release/hello-wasi.wasm
 
# Run with Wasmtime v44.0.0
wasmtime target/wasm32-wasip1/release/hello-wasi.wasm
# => Output: Hello from WASI!
# => Output: PATH: not set

# Basic execution: no filesystem access, no network
wasmtime run hello-wasi.wasm
# => Output: Hello from WASI!
# => Runtime: WASIp1 (Wasmtime v44 supports WASIp1, WASIp2, experimental WASIp3)
 
# Check Wasmtime version
wasmtime --version   # => wasmtime-cli 44.0.0
 
# Grant file system access with --dir
wasmtime run --dir /tmp file-reader.wasm
# => /tmp is preopened: WASI module can read/write files in /tmp
# => WASI host path /tmp is mapped to WASI guest path /tmp (same name)
 
# Map host path to a different guest path
wasmtime run --dir /home/user/data::/ file-reader.wasm
# => /home/user/data (host) mapped to / (guest)
# => module sees / as its root
 
# Pass environment variables
wasmtime run --env MY_VAR=hello env-reader.wasm
# => std::env::var("MY_VAR") returns "hello" in Rust
 
# Pass command-line arguments to the Wasm module
wasmtime run -- calculator.wasm add 10 20
# => std::env::args() in Rust sees: ["calculator.wasm", "add", "10", "20"]
 
# Run with fuel limit (prevent infinite loops in untrusted code)
wasmtime run --fuel 1000000 compute.wasm
# => module gets 1,000,000 fuel units (instructions) before termination
# => OutOfFuel error if exceeded: useful for sandbox environments
 
# Run a WASIp2 component (different from WASIp1 module)
wasmtime run --wasi inherit-stdio component.wasm
# => --wasi flags configure WASIp2 world capabilities

// src/main.rs — WASI file I/O
use std::fs;
use std::io::{self, Write};
 
fn main() -> io::Result<()> {
    // Reading a file: works like normal Rust std::fs
    // Requires --dir containing /data to be granted by runtime
    let content = fs::read_to_string("/data/input.txt")?;
    // => WASI: read_to_string calls fd_read WASI syscall
    // => runtime checks if /data was preopened
    // => error if directory not granted: "capability not available"
 
    println!("Read {} bytes", content.len()); // => print byte count
 
    // Process the content
    let processed: String = content
        .lines()
        .map(|line| line.to_uppercase())       // => convert each line to uppercase
        .collect::<Vec<_>>()
        .join("\n");                            // => rejoin lines
 
    // Writing a file: also requires --dir to be granted
    let mut out = fs::File::create("/data/output.txt")?;
    // => creates or overwrites output.txt in preopened /data
    out.write_all(processed.as_bytes())?;      // => write UTF-8 bytes to file
    out.flush()?;                               // => flush OS buffers
 
    println!("Wrote processed output to /data/output.txt");
    Ok(())  // => main returns Ok(()) on success; Err propagates as non-zero exit
}

# Create test data
mkdir -p /tmp/wasi-data
echo -e "hello world\nfoo bar\nbaz qux" > /tmp/wasi-data/input.txt
 
# Compile the WASI binary
cargo build --target wasm32-wasip1 --release
 
# Run with /tmp/wasi-data preopened as /data (host::guest mapping)
wasmtime run \
  --dir /tmp/wasi-data::/data \
  target/wasm32-wasip1/release/file-io.wasm
 
# => Output: Read 21 bytes
# => Output: Wrote processed output to /data/output.txt
 
# Verify output
cat /tmp/wasi-data/output.txt
# => HELLO WORLD
# => FOO BAR
# => BAZ QUX

// node-wasi.js — running a WASIp1 module in Node.js
import { WASI } from "node:wasi"; // => experimental built-in
import { readFile } from "node:fs/promises";
 
// Configure WASI with capabilities
const wasi = new WASI({
  version: "preview1", // => WASIp1 only; "preview2" not yet supported
  args: ["my-program", "--verbose"], // => argv passed to the module
  env: {
    HOME: "/tmp", // => environment variables
    PATH: "",
  },
  preopens: {
    "/data": "/tmp/wasi-data", // => guest path: host path mapping
    // => module can access /data, which maps to /tmp/wasi-data on host
  },
  returnOnExit: true, // => return instead of process.exit() on main() return
  stdin: process.stdin.fd, // => inherit stdin from Node.js process
  stdout: process.stdout.fd, // => inherit stdout from Node.js process
  stderr: process.stderr.fd, // => inherit stderr from Node.js process
});
 
// Load the .wasm binary
const wasmBytes = await readFile("./hello-wasi.wasm"); // => read binary file
const { module, instance } = await WebAssembly.instantiate(
  wasmBytes,
  wasi.getImportObject(), // => WASI provides the import object
  // => imports: { wasi_snapshot_preview1: { ... } }
);
 
// Start the module (calls _start, which calls main())
wasi.start(instance); // => runs the WASI module
// => Output: Hello from WASI!
// => Output: PATH: not set

# Run the Node.js WASI script
node --experimental-wasi-unstable-preview1 node-wasi.js
# => flag required: marks WASI API as experimental
# => Output: Hello from WASI!
# => (experimental API warning may appear on stderr)

# Compile with full DWARF debug info embedded in the .wasm file
emcc source.c -g -o debug.wasm
# => -g: embed DWARF debug info in the .wasm binary
# => debug.wasm is much larger (MB larger than release)
# => Chrome DevTools WASM extension reads DWARF from the embedded section
 
# Compile with separate DWARF file (smaller production binary)
emcc source.c \
  -g \
  -gseparate-dwarf=debug.wasm.dwp \
  -o release.wasm
# => release.wasm: no debug info (production-sized)
# => debug.wasm.dwp: all DWARF info (can be served separately)
# => release.wasm contains a "external debug info" section pointing to .dwp URL
 
# Compile C++ with debug info and optimize (common in production builds)
em++ source.cpp \
  -O2 \
  -g \
  -gseparate-dwarf=app.wasm.dwp \
  -o app.wasm \
  -o app.js
# => optimized Wasm with separate debug info
# => optimization affects debuggability: -O0 gives best debug experience
 
# For Rust (wasm-pack debug build):
wasm-pack build --target web --dev
# => --dev: includes debug info (DWARF), no wasm-opt, assertions enabled
# => similar to emcc -g

# Step 1: Compile with debug info
emcc source.c -O2 -g -o with-debug.wasm
ls -lh with-debug.wasm     # => 2.1M (large: includes DWARF)
 
# Step 2: Strip debug info from production binary
wasm-opt with-debug.wasm -o release.wasm --strip-dwarf
# => wasm-opt (Binaryen version_129) removes DWARF sections
# => release.wasm: production-sized binary without debug data
ls -lh release.wasm        # => 410K (stripped of debug sections)
 
# Alternative: use LLVM's llvm-strip
llvm-strip -g with-debug.wasm -o release-llvm.wasm
# => same result: strips debug sections only
 
# Step 3: Extract debug info using llvm-objcopy (if using separate DWARF)
# (Emscripten's -gseparate-dwarf does this during compilation)
 
# Step 4: Deploy release.wasm to CDN
# Deploy debug info (separate file) to dev tooling server or conditional endpoint
 
# Verify production binary has no debug sections
wasm-objdump -x release.wasm | grep -i "debug"
# => (no output): no debug sections in production binary
 
wasm-objdump -x with-debug.wasm | grep -i "debug"
# => Custom Section ".debug_info": contains DWARF info
# => Custom Section ".debug_line": line number mapping
# => Custom Section ".debug_abbrev": DWARF abbreviations

# 1. Install the Chrome extension:
# Chrome Web Store: "C/C++ DevTools Support (DWARF)"
# URL: https://chromewebstore.google.com/detail/cc++-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb
# => extension reads DWARF sections from .wasm files loaded by the page
 
# 2. Compile with debug info (DWARF embedded)
emcc source.c -g -O0 -o debug.wasm -o debug.js
# => -O0: no optimization = best variable visibility in debugger
# => -g: DWARF debug info included
 
# 3. Serve on localhost (WASM debugging requires HTTP, not file://)
npx serve .
# => localhost:3000
 
# 4. Open Chrome, navigate to your page
# 5. Open DevTools (F12) → Sources tab
# 6. After loading the page, Wasm source files appear in Sources:
# =>   wasm://wasm/source.c  ← your C source file
# =>   Click to set breakpoints on C source lines
 
# 7. Variable inspection in DevTools console during a breakpoint:
# => Hover over variables: see C-level names and values
# => Watch panel: add expressions like "a + b" in C context
# => Call stack: shows C function names (not wasm function indices)
 
# For Rust + wasm-pack:
wasm-pack build --target web --dev    # => debug build includes DWARF
# => Same DevTools workflow applies
# => Rust source lines visible in DevTools when extension is installed