Fundamentals

 source (Rust, C, C++, Go, Zig, Kotlin, ...)
        │  compiler (LLVM, Emscripten, wasm-bindgen, ...)
        ▼
   module.wasm ── fetch ──► compile ──► WebAssembly.Module
                                        (stateless, shareable,
                                         postMessage-able)
                                              │ + import object
                                              ▼
                                    WebAssembly.Instance
                                    ├─ exports.fn(...)   ◄─ JS
                                    ├─ exports.memory    (bytes)
                                    └─ imports ─► JS / host

 module.wasm
 ├─ magic \0asm, version 1
 ├─ type      function signatures (and GC struct/array types)
 ├─ import    funcs, tables, memories, globals, tags from host
 ├─ function  index → type for each defined function
 ├─ table     tables of references (funcref / externref)
 ├─ memory    linear memories: min / max pages, shared?
 ├─ tag       exception tags (exception handling)
 ├─ global    typed globals, mutable or immutable
 ├─ export    names for funcs / tables / memories / globals
 ├─ start     function run automatically at instantiation
 ├─ elem      element segments: fill tables (call_indirect)
 ├─ datacount number of data segments (bulk memory)
 ├─ code      function bodies: locals + instructions
 ├─ data      data segments: initial bytes for memory
 └─ custom    "name", DWARF ".debug_*", "producers",
              "sourceMappingURL", "target_features", ...

const { add64, count } = instance.exports as {
  add64(a: bigint, b: bigint): bigint;
  count(): number; // i32
};
add64(1n, 2n);            // 3n
add64(1, 2);              // TypeError: must be BigInt
const u = count() >>> 0;  // reinterpret i32 as unsigned

const imports = {
  env: {
    log: (x: number) => console.log(x),
    now: () => performance.now(),
  },
};
const { instance, module } =
  await WebAssembly.instantiateStreaming(
    fetch("/app.wasm"), imports,
  );
const mem = instance.exports.memory as WebAssembly.Memory;

const mem = new WebAssembly.Memory({
  initial: 1,    // 64 KiB
  maximum: 256,  // 16 MiB
});
let u8 = new Uint8Array(mem.buffer);
mem.grow(1);           // or Wasm's memory.grow / malloc
u8.length;             // 0: the old buffer is detached
u8 = new Uint8Array(mem.buffer); // re-view after growth

Content-Type: application/wasm
Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'
Cross-Origin-Opener-Policy: same-origin      (threads only)
Cross-Origin-Embedder-Policy: require-corp   (threads only)

 linear memory (Uint8Array over memory.buffer)
 0        ptr                  ptr+len             end
 ├────────┼── "héllo" UTF-8 ──┼───────────────────┤
          ▲ JS writes here via TextEncoder.encodeInto
          └ Wasm reads (ptr, len); returns (ptr, len)

type Exports = {
  memory: WebAssembly.Memory;
  alloc(len: number): number; // returns ptr
  free(ptr: number, len: number): void;
  upper(ptr: number, len: number): number; // new len
};
const enc = new TextEncoder();
const dec = new TextDecoder();
 
function callUpper(x: Exports, s: string): string {
  const bytes = enc.encode(s);
  const ptr = x.alloc(bytes.length);
  // view AFTER alloc: alloc may have grown memory
  new Uint8Array(x.memory.buffer, ptr, bytes.length)
    .set(bytes);
  const len = x.upper(ptr, bytes.length);
  const out = new Uint8Array(x.memory.buffer, ptr, len);
  const result = dec.decode(out);
  x.free(ptr, bytes.length);
  return result;
}

const { instance } = await WebAssembly.instantiate(
  bytes,
  imports,
  {
    builtins: ["js-string"],      // wasm:js-string imports
    importedStringConstants: "'", // (import "'" "hi" ...)
  },
);

// Vite: typed ?init import
import init from "./math.wasm?init";
 
const instance = await init({ env: { abort() {} } });
const { add } = instance.exports as {
  add(a: number, b: number): number;
};

// Node: source phase import (Node 24.5+ / 22.19+)
import source mathMod from "./math.wasm";
 
const a = await WebAssembly.instantiate(mathMod, {});
const b = await WebAssembly.instantiate(mathMod, {});

 main thread                     worker × N
 ───────────                     ──────────
 compileStreaming ─ Module ─────► postMessage({ module, memory })
 new Memory({ shared: true }) ──► instantiate(module, { env: { memory } })
                                  Atomics.wait / notify on memory

self.onmessage = async (e: MessageEvent<{
  mod: WebAssembly.Module; input: Float32Array;
}>) => {
  const inst = await WebAssembly.instantiate(e.data.mod, {});
  const x = inst.exports as {
    memory: WebAssembly.Memory;
    alloc(n: number): number;
    process(ptr: number, n: number): void;
  };
  const n = e.data.input.length;
  const ptr = x.alloc(n * 4);
  const view = new Float32Array(x.memory.buffer, ptr, n);
  view.set(e.data.input);
  x.process(ptr, n);
  const out = view.slice(); // copy out before posting
  self.postMessage(out, [out.buffer]);
};

const imports = {
  env: {
    // async import: Wasm sees a normal sync call
    fetchLen: new WebAssembly.Suspending(
      async (id: number): Promise<number> => {
        const r = await fetch(`/item/${id}`);
        return (await r.arrayBuffer()).byteLength;
      },
    ),
  },
};
const { instance } = await WebAssembly.instantiate(
  bytes, imports,
);
// export returns a Promise now
const run = WebAssembly.promising(
  instance.exports.run as (id: number) => number,
);
const n: number = await run(7);

export async function loadWasm<T>(
  url: string | URL,
  imports: WebAssembly.Imports = {},
): Promise<T> {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status} ${url}`);
  const type = res.headers.get("content-type") ?? "";
  const { instance } = type.startsWith("application/wasm")
    ? await WebAssembly.instantiateStreaming(res, imports)
    : await WebAssembly.instantiate(
        await res.arrayBuffer(), imports,
      );
  return instance.exports as T;
}

// (func (result v128) i32.const 0 i8x16.splat i8x16.popcnt)
const SIMD = new Uint8Array([
  0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 123,
  3, 2, 1, 0, 10, 10, 1, 8, 0, 65, 0, 253, 15, 253, 98,
  11,
]);
const hasSimd = WebAssembly.validate(SIMD);
const url = hasSimd ? "/app.simd.wasm" : "/app.wasm";

interface Raw {
  memory: WebAssembly.Memory;
  alloc(n: number): number;
  free(p: number, n: number): void;
  sum_f32(p: number, n: number): number;
}
export function wrap(x: Raw) {
  return {
    sum(values: Float32Array): number {
      const bytes = values.length * 4;
      const p = x.alloc(bytes);
      try {
        new Float32Array(x.memory.buffer, p, values.length)
          .set(values);
        return x.sum_f32(p, values.length);
      } finally {
        x.free(p, bytes);
      }
    },
  };
}

const mod = await WebAssembly.compileStreaming(
  fetch("/kernel.wasm"),
);
const workers = Array.from(
  { length: navigator.hardwareConcurrency },
  () => new Worker(
    new URL("./wasm.worker.ts", import.meta.url),
    { type: "module" },
  ),
);
for (const w of workers) w.postMessage({ mod });

const table = new WebAssembly.Table({
  element: "externref", initial: 4,
});
table.set(0, document.body); // any JS value
const imports = {
  env: {
    table,
    log: (ptr: number, len: number) =>
      console.log(readStr(ptr, len)),
    onTick: (dt: number) => update(dt),
  },
};

import { createServer } from "node:http";
import { readFile } from "node:fs/promises";
 
createServer(async (req, res) => {
  const file = `./dist${req.url}`;
  if (file.endsWith(".wasm")) {
    res.setHeader("Content-Type", "application/wasm");
  }
  res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
  res.setHeader(
    "Cross-Origin-Embedder-Policy", "require-corp",
  );
  res.end(await readFile(file));
}).listen(8080);