API Reference

Compile a single Julia function for the given concrete argument-type tuple to a self-contained WASM module. The result is a binary `Vector{UInt8}` ready to write to disk and instantiate via `WebAssembly.instantiate`. `optimize=true` runs `wasm-opt` for an ~80–90% size reduction (requires Binaryen). Soundness defaults: `strict=true` raises a `WasmCompileError` (naming the construct + source location) rather than emit a wrong value for an unsupported construct — pass `strict=false` for permissive stub-and-trap; `validate=true` runs `wasm-tools validate` on the output and raises `WasmValidationError` instead of returning malformed bytes.

Compile multiple `(f, arg_types[, name])` entries into one module. Functions in the same call share the WasmGC type space and can call each other directly — this is the entry point for vector-bridge patterns and any multi-function island. Callee discovery defaults to `:trim` — the upstream closed-world collection (`Compiler.typeinf_ext_toplevel`, the same machinery behind `juliac --trim`) walks every reachable invoke in one consistent inference world. Pass `discovery=:legacy` for the previous curated-whitelist walker.

Lower-level entry that takes a pre-built `CodeInfo` instead of starting from a function. Used by Therapy.jl's `@island` compiler when it has already computed the IR for a closure body.

Like `compile_multi` but reuses a shared `Base`-overlay state across the batch. Suitable when compiling many unrelated functions in the same process and the per-call `Base` walk dominates.

Run Binaryen `wasm-opt` on a previously-compiled module. Same effect as passing `optimize=true` to `compile`.

Primitive type that maps to WASM `externref`. Use it in function signatures to accept opaque JavaScript handles (DOM elements, JS objects, function references). See the JS Interop section of the Manual.

Type-safe handle for a WASM global variable at compile-time index `IDX`. Phantom-parameter — `WasmGlobal` arguments do not become WASM function parameters; the compiler emits `global.get` / `global.set` instead. Multiple functions in the same `compile_multi` call share globals.

Mutable container for hand-built modules: types, functions, imports, exports, tables, memories, data segments. Most users go through `compile` / `compile_multi`; reach for `WasmModule` when you need host-import wiring or custom memory/table layouts.

Declare a function the host (JavaScript) must provide. Pure-numeric variants accept `Vector{NumType}`; signatures that include `ExternRef` require `WasmValType[…]` to hit the reference-type overload.

Append a function to the module and (optionally) export it under a chosen name. The high-level `compile` / `compile_multi` paths call these for you.

Manually add WASM globals — the explicit form behind `WasmGlobal{T, IDX}`. Use when you need named globals or non-default initializers.

Add a function-reference or externref table — required for `call_indirect` (multiple-dispatch dynamic dispatch). `reftype` is `FuncRef` or `ExternRef`.

Linear-memory escape hatch. Prefer WasmGC structs/arrays over linear memory for new code.

Register a Julia package's compilable function set with WasmTarget so its overlays + entry-points are discoverable. Powers the auto-discovery that lets a notebook do `using SomePackage` and have its WASM-compatible functions show up automatically.

Compile against a set of pre-registered packages so their overlays + helper definitions are visible to the Julia compiler before IR extraction.

Internal hooks — register WasmTarget's built-in package overlays at module load, and detect `using`/`import` statements in source for auto-registration.

Drop-in replacements for `compile` / `compile_multi` that memoize on the input IR + arg types. Returns the cached bytes immediately on hit — useful for hot-reload dev loops and CI builds that compile the same islands repeatedly.

Process-wide cache controls. `cache_stats()` returns a NamedTuple of hit/miss counts.

Compile and emit a source-map alongside the WASM bytes so browser DevTools can step through the original Julia line numbers when an exception throws inside a compiled function.

Serialize a manually-built `WasmModule` to WASM binary.

Snapshot of the compilation context (registered types, function table, overlay tables) suitable for reuse across many calls. Therapy.jl uses this between hot-reload iterations.

Mutable registries the compiler walks while lowering IR — types it has seen, functions it has emitted. Exposed for advanced consumers that need to inspect or pre-seed compilation state.

Internal hook used by Therapy.jl's `@island` compiler to lower event-handler closures with DOM-binding metadata. Not intended for direct use.