Memória linear: regras, alocação e armadilhas comuns Memória

• Entenda que a memória de WebAssembly é uma memória linear (Memory) que pode crescer, mas não cresce automaticamente como em outros ambientes. Gerencie o crescimento com cuidado para evitar overruns de ponteiros.
• Accessos fora dos limites resultam em traps. Sempre valide offsets antes de ler/escrever через memory.buffer. Use Visualizações (TypedArray/DataView) para ler e escrever em memória com offsets conhecidos.
• Ao usar chamadas de função que manipulam buffers, prefira estratégias de alocação explícitas (alloc/free) ou APIs que encapsulem esse comportamento (ex.: alloc em um heap WASM típico). Evite manipular carrinhos de memória sem coordenação entre lado WASM e JS.
• Considere o crescimento da memória com cautela: defina initial e maximum adequados ao seu caso. Use memory.grow apenas quando necessário e monitorize o impacto no tempo de carga.

// Exemplo conceitual (Rust + wasm-bindgen não obrigatório)
// Este é apenas um lembrete do padrão: você aloca, escreve e lê, sem saltos de offsets não verificados.
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn write_buffer(mem: &mut [u8], off: usize, data: &[u8]) {
  mem[off..off+data.len()].copy_from_slice(data);
}

Integração WASM & JS: chamadas, tipos e strings Interoperabilidade

• Evite dependência direta de ponteiros do JS para chamadas exportadas; prefira bindings que traduzam tipos entre as duas plataformas (i.e., wasm-bindgen, wasm-pack, ou uma camada de wrapper).
• Tipos numéricos simples (i32, i64, f32, f64) costumam mapear diretamente. Strings, arrays e objetos complexos exigem um contrato claro de memória: alocações, cópia, e recuperação de resultados.
• Não passe strings do JS diretamente para funções WASM sem um binding que gerencie a codificação (UTF-8) e o lifecycle da memória. Strings costumam exigir alocação de memória no espaço WASM e copiar o conteúdo.
• Para evitar drift de APIs, adote wrappers estáveis (ex.: wasm-bindgen) que implementam a passagem de strings como CharPtr/UTF-8 ou objetos simples já serializados para o lado WASM.

// Exemplo simples com wasm-bindgen
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn add(a: i32, b: i32) -> i32 {
  a + b
}

#[wasm_bindgen]
pub fn greet(name: &str) -> String {
  format!("Olá, {}!", name)
}

// Uso JavaScript (assumindo pacote gerado por wasm-bindgen)
import init, { add, greet } from './pkg/wasm_module.js';

async function run() {
  await init();
  console.log('add(2,3) =', add(2, 3));        // 5
  console.log(greet('Mundo'));                // Olá, Mundo!
}
run();

Tratamento de erros e exceções: não perca o controle Robustez

• Exceções em WASM MVP não são tão universais; para produção, exponha erros via Result (ou equivalente) e converta para erros JS de forma controlada.
• Brindar mensagens de erro úteis para o usuário/cliente é essencial. Não exponha apenas códigos; associe mensagens amigáveis e códigos de diagnóstico.
• Use wrappers que transformem falhas do lado WASM em throws compatíveis com JS, ou retorne estruturas simples que o JavaScript possa interpretar com clareza.

// Exemplo com Result e JsValue (via wasm-bindgen)
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn might_fail(input: i32) -> Result {
  if input < 0 {
    Err(JsValue::from_str("Entrada deve ser não-negativa"))
  } else {
    Ok(input * 2)
  }
}

Build, performance e debugging: práticas que aceleram a produção Build/Performance

• Escolha a toolchain certa: wasm-pack ou cargo + wasm-bindgen para gerar o wrapper JS de forma segura e previsível.
• Otimize para produção: rode wasm-opt (quando disponível) para reduzir tamanho e melhorar tempo de carregamento; valide trade-offs entre size e speed.
• Habilite source maps para WASM e para as ligações com JS para facilitar o debugging do código gerado. Testes de integração devem cobrir cenários de interação WASM/JS.
• Defina um pipeline de CI que inclua verificação de compatibilidade entre versões do compilador, bindings e o runtime onde o WASM será executado.

// Observação prática (pseudocomando)
# Construção típica com wasm-pack
wasm-pack build --target web --dev
# Em produção, otimize
wasm-opt -Oz dist/my_wasm_bg.wasm -o dist/my_wasm_bg.wasm