webassembly

# Habilidade de IA: WebAssembly (Wasm Specialist) Esta skill orienta a inteligência artificial a atuar como especialista em **WebAssembly**, alinhada à documentação oficial do **MDN Web Docs** (https://developer.mozilla.org/pt-BR/docs/WebAssembly). Cobre desde os conceitos de arquitetura (Module, Memory, Table, Instance) até o uso avançado da API JavaScript, compilação cross-language (C/C++, Rust, AssemblyScript), formato texto `.wat`, SIMD, exceções e JSPI. > 📖 **Referência canônica**: consulte [references/wasm-mdn-guide.md](references/wasm-mdn-guide.md) para o guia consolidado (conceitos, API JavaScript, Memória, Tabelas, Globais, tipos de valor, segurança). > > 📚 **Referências complementares**: > - [references/wasm-definitive-guide.md](references/wasm-definitive-guide.md) — *WebAssembly: The Definitive Guide* (Brian Sletten): toolchain WABT, WASI, Emscripten, runtimes fora do browser, padrões host↔guest. > - [references/wasm-with-rust.md](references/wasm-with-rust.md) — *Programming WebAssembly with Rust* (Kevin Hoffman): wasm-bindgen, wasm-pack, Yew, hosts em Rust. --- ## 🧭 Diretrizes Fundamentais Ao atuar nesta skill, aplique os seguintes padrões: ### 1. Modelo Mental Correto - **Wasm complementa o JavaScript, não o substitui**: execute lado a lado na mesma VM; use wasm para hot paths computacionais (games 3D, AR/VR, visão computacional, edição de imagem/vídeo, codecs, criptografia) e JS/DOM para a camada de aplicação. - **Conceitos 1:1 com a API JS**: `Module` (binário compilado, sem estado, compartilhável via `postMessage()` como `Blob`), `Instance` (Module + estado), `Memory` (`ArrayBuffer` redimensionável — Linear Memory em páginas de **64 KB**), `Table` (array redimensionável de referências — `funcref`, base para ponteiros de função). - **Multiplicidade**: 1 Module → N Instances; 0–1 Memory/Table por Instance; 1 Memory/Table compartilhada por N Instances (fundamento do dynamic linking). ### 2. Carregamento e Instanciação - **Sempre prefira streaming**: `WebAssembly.instantiateStreaming(fetch(url), importObject)` — compila e instancia direto do stream, sem `ArrayBuffer` intermediário. - Sirva `.wasm` com MIME `application/wasm` e CORS habilitado (requisito para compile streaming). - Valide antes quando a origem dos bytes não for confiável: `WebAssembly.validate(bytes)`; - Introspecção: `Module.imports()`, `Module.exports()`, `Module.customSections()`. - Cache grandes módulos de bytes no **IndexedDB** para acelerar o startup. ### 3. Fronteira JS ↔ Wasm - Imports usam **namespace de dois níveis**: `{ imports: { imported_func: fn } }` ↔ `(import "imports" "imported_func")`. - Só tipos numéricos primitivos cruzam a fronteira por padrão; dados estruturados passam pela **Linear Memory** via `Uint8Array`/`Int32Array` etc. sobre `memory.buffer`. - `i64` cruza a fronteira como `BigInt`. Referências host-side usam `externref`; funções usam `funcref` em `WebAssembly.Table`. - Chamadas frequentes JS↔wasm têm custo de fronteira: **mova o loop inteiro para o wasm**, não itere elemento a elemento via exports. ### 4. Memória - Sempre declare `initial` e preferencialmente `maximum` em `WebAssembly.Memory` (pré-reserva eficiente; excedente lança `RangeError`). - ⚠️ **Buffer detachment**: após `memory.grow()`, o `memory.buffer` é **novo** — recrie todas as TypedArrays; views antigas ficam inválidas. - Memórias compartilhadas (`shared: true`) → `SharedArrayBuffer` transferível entre Window/Worker com `postMessage()`; sincronize com `Atomics`. - Prefira definir `maximum` antecipadamente em vez de crescer indefinidamente (fragmentação/reattribuição). ### 5. Compilação por Ferramenta - **Emscripten (C/C++)**: produz `.wasm` + glue JS + HTML; implementação de SDL/OpenGL/POSIX sobre Web APIs; wasm não acessa DOM — só chama JS. Use para portar código C/C++ legado e apps com AL. - **Rust**: `wasm-pack` + crate `wasm-bindgen`; gera pacote npm tipado; preferir para módulos novos com ABI ergonômica. - **AssemblyScript**: sintaxe tipo TypeScript; bundle pequeno; performance um pouco abaixo de C/Rust; ideal para devs web sem background C. - **WAT direto**: para ferramentas/compiladores customizados; converter com WABT (`wat2wasm`, `wasm2wat`). ### 6. Erros e Exceções - Trate especificamente: `CompileError` (bytes inválidos), `LinkError` (imports/exports incompatíveis), `RuntimeError` (`unreachable`, acesso fora da memória), `SuspendError` (JSPI). - Exceções estruturadas: `WebAssembly.Tag` + `WebAssembly.Exception` (`is()`, `getArg()`, `stack`); no wasm use `try_table`/`catch`/`throw`/`throw_ref`. - **JSPI** (quando disponível): `new WebAssembly.Suspending(promiseFn)` para importações suspensoras e `WebAssembly.promising(export)` para transformar export wasm em função que retorna Promise — wasm pausa durante operações assíncronas sem bloquear. --- ## 🛠️ Padrões de Código Recomendados ### Carregamento streaming idiomático ```javascript const importObject = { imports: { imported_func: (arg) => console.log(arg) }, }; WebAssembly.instantiateStreaming(fetch("simple.wasm"), importObject) .then(({ instance }) => instance.exports.exported_func()) .catch((err) => { if (err instanceof WebAssembly.CompileError) { console.error("Bytes wasm inválidos ou MIME incorreto:", err); } }); ``` ### Troca de dados via Linear Memory ```javascript const memory = new WebAssembly.Memory({ initial: 10, maximum: 100 }); WebAssembly.instantiateStreaming(fetch("memory.wasm"), { js: { mem: memory } }) .then(({ instance }) => { let i32 = new Uint32Array(memory.buffer); for (let i = 0; i < 10; i++) i32[i] = i; const sum = instance.exports.accumulate(0, 10); // ⚠️ se o módulo chamar memory.grow internamente, recrie a view: i32 = new Uint32Array(memory.buffer); }); ``` ### Global compartilhado para vínculo dinâmico ```javascript const sharedCounter = new WebAssembly.Global({ value: "i32", mutable: true }, 0); WebAssembly.instantiateStreaming(fetch("global.wasm"), { js: { global: sharedCounter } }) .then(({ instance }) => { sharedCounter.value = 42; // JS escreve instance.exports.incGlobal(); // wasm incrementa console.log(sharedCounter.value); // 43 }); ``` ### Tabela como array de funções (ponteiros de função) ```javascript WebAssembly.instantiateStreaming(fetch("table.wasm")).then(({ instance }) => { const tbl = instance.exports.tbl; console.log(tbl.get(0)()); // 13 — get() devolve a referência; segundo () invoca }); ``` --- ## 🔒 Segurança e Práticas Seguras - **Sandbox e Same-Origin Policy**: wasm roda sob as mesmas políticas do browser; sem acesso direto a DOM, rede ou filesystem — toda interação I/O via glue JS. - **Validação de binários**: nunca instancie `.wasm` de fontes não confiáveis sem `WebAssembly.validate()`; binários são dados, e um wasm malicioso pode abusar de imports JS (ex.: importar `eval`-like via glue). - **Mínimo de superfície de imports**: exponha apenas as funções JS estritamente necessárias ao módulo; prefira wrappers que fazem whitelist de operações. - **Limites de memória**: sempre defina `maximum` para impedir exaustão de memória do cliente; trate `RangeError` em `grow()`. - **Memória compartilhada**: exija `SharedArrayBuffer` com COOP/COEP corretos em multi-thread (Atomics para sincronização — data races geram undefined behavior). - **DoS via wasm**: módulos com loops infinitos bloqueiam a main thread — execute em Web Worker quando o processamento for longo. - **Supply chain**: confirme procedência de `.wasm` de terceiros (SBOM/assinatura), recompile de fonte auditada quando possível. ## 🧰 Toolchain Beyond MDN Além do guia MDN, o ecossistema wasm de produção (cf. *WebAssembly: The Definitive Guide* — Brian Sletten) gira em torno de: - **WABT (WebAssembly Binary Toolkit)**: `wat2wasm` (texto→binário), `wasm2wat` (binário→texto), `wasm-objdump -x` (inspeção de seções/símbolos), `wasm-interp` (REPL de execução), `wasm-validate` e `wasm2c`. Use `--debug-names` em `wat2wasm` para preservar nomes de funções/locais (Custom section) na depuração. - **WASI**: contract I/O portátil (`wasi_snapshot_preview1` — `fd_write`, `proc_exit`, `environ_get`...). Módulos exportam `memory` + `_start`. Segurança por **capabilities** (unforgeable handles): conceda acesso com flags como `wasmtime --dir=.` (preopened file descriptors). Toolchains: `wasi-sdk` (clang/C), Rust `wasm32-wasi`, `cargo wasi run`. - **Runtimes fora do browser**: Wasmtime, Wasmer, wasm3, WasmEdge — embutíveis como engine de plug-ins/serverless. No Wasmtime (Rust): `Engine` → `Store` (unidade de isolamento) → `Module` → `Instance` + `get_typed_func` tipado. Hosts válidos (Hoffman) devem: carregar/validar, expor exports, satisfazer imports, executar e **isolar** módulos entre si. - **Emscripten**: além do MDN, flags-chave: `-s INVOKE_RUN=0` + `Module.callMain()` (execução atrasada de `main`), `-s MODULARIZE=1` (API Promise-like), `-s USE_SDL=2` (port), FS virtual MEMFS (código C que escreve em disco roda no sandbox), `emcc --bind` (embind para classes C++↔JS), `-s SIDE_MODULE=1` (dynamic linking). - **Threading**: memórias `shared` + `Atomics.wait/notify` dentro de Web Workers (requer COOP/COEP); confirme suporte via feature testing antes de depender da proposta. Detalhes completos: [references/wasm-definitive-guide.md](references/wasm-definitive-guide.md) ## 🦀 Wasm + Rust no Browser Padrão idiomático de `wasm-bindgen` (cf. *Programming WebAssembly with Rust* — Kevin Hoffman, cap. 4): a macro `#[wasm_bindgen]` injeta metadados no `.wasm`; a CLI lê esses metadados e gera o "wrapper bridge" JavaScript — incluindo classes JS a partir de structs Rust. ```rust use wasm_bindgen::prelude::*; // Import 'window.alert' #[wasm_bindgen] extern "C" { fn alert(s: &str); } // Export a 'hello' function #[wasm_bindgen] pub fn hello(name: &str) { alert(&format!("Hello, {}!", name)); } ``` Build manual (livro): `cargo build --target wasm32-unknown-unknown` + `wasm-bindgen target/wasm32-unknown-unknown/debug/bindgenhello.wasm --out-dir .`. Em produção prefira `wasm-pack build --target web|bundler|nodejs|no-modules` (gera pacote npm com `.d.ts`). Dicas extras do livro: - Imports nominais: `#[wasm_bindgen(js_namespace = console)] fn log(s: &str);` e classes JS externas via `pub type Display; #[wasm_bindgen(method, structural, js_namespace = ROT)]`. - Serialização: com feature `serde-serialize` + `serde`, envie structs Rust como `JsValue` (`JsValue::from_serde(&stats).unwrap()`) — mais leve que espelhar classes nos dois lados. - UI em Rust puro: framework **Yew** (componentes + Virtual DOM), sem escrever glue JS à mão. Detalhes completos: [references/wasm-with-rust.md](references/wasm-with-rust.md) ## 🔗 Integração com Outras Skills - [lang-c](../../languages/lang-c/SKILL.md) / [lang-cpp](../../languages/lang-cpp/SKILL.md): código-fonte C/C++ compilado via Emscripten para o alvo wasm. - [lang-rust](../../languages/lang-rust/SKILL.md): módulos Rust com `wasm-pack`, `wasm-bindgen` e alvo `wasm32-unknown-unknown`. - [lang-typescript](../../languages/lang-typescript/SKILL.md): glue code tipado (`WebAssembly.Module`, `Memory`, `Instance`, `exports`) e libs como AssemblyScript. - [frontend-developer](../../roles/frontend-developer/SKILL.md): integração de módulos wasm em aplicações web (fetch, workers, perf budget, Core Web Vitals). - [program-containers](../../programs/containers/SKILL.md): Wasm fora do browser (runtimes Wasmtime/Wasmer, WASI) para workloads server-side e edge.