feat(wasm): closes #76 — runtime WebAssembly host (PoC, wasmi) (#705)

* feat(wasm): closes #76 — runtime WebAssembly host (PoC, wasmi)

Lets a binary built for `--target macos/linux/windows/ios/android` load
third-party `.wasm` modules at runtime via `WebAssembly.instantiate(...)`
— closing the host-side gap with Node and matching the issue's PoC scope.

Engine: wasmi 0.50 (pure-Rust interpreter), in a separate
`perry-wasm-host` crate so the default Perry build never pulls wasmi in.
Linking is auto-detected when codegen sees any `WebAssembly.*` reference;
the `--enable-wasm-runtime` flag stays available to force-link for
dlopen/FFI scenarios that have no static reference.

Surface (Perry MVP shape; standard async surface tracked as follow-up):
  const bytes = embedWasm("./add.wasm");          // compile-time embed
  const inst  = WebAssembly.instantiate(bytes);   // sync, opaque handle
  inst.exports.add(2, 3);                         // standard JS shape
  WebAssembly.callExport(inst, "add", 2, 3);      // explicit helper
  WebAssembly.validate(bytes);                    // bool

`inst.exports.<method>(...)` is recognised syntactically when the local
was tagged at var-decl time as a wasm instance (init was
`WebAssembly.instantiate(...)`) — this avoids stealing unrelated
`module.exports.foo()` calls from CJS aggregators. `embedWasm("...")`
reads the file at HIR-lower time relative to the importing source and
bakes the bytes into the binary as a `Uint8Array` literal (sidesteps the
in-flight TC39 import-attributes proposal per maintainer preference on
the issue thread).

The `js_webassembly_*` shims in perry-runtime forward to a stable C ABI
on perry-wasm-host. perry-runtime never depends on wasmi at the cargo
level — link-time resolution only. Programs without any `WebAssembly.*`
usage stay exactly the same size (verified: 0.9MB vs 1.9MB on the test).

Validation:
  - cargo test -p perry-wasm-host: 2/2 (validate + add 2+3=5)
  - test-files/test_wasm_add.ts compiles without --enable-wasm-runtime
    (auto-detected) and prints OK
  - workspace test suite green (excluding cross-host UI crates per
    CLAUDE.md's exclusion list)
  - default build (no WebAssembly.*) compiles + runs unchanged

Out of scope (follow-ups, not this PR):
  - Standard `Promise<{module, instance}>` async surface
  - Host imports beyond numeric (externref, strings, structs)
  - `instantiateStreaming`
  - Wasmtime engine selection (`--enable-wasm-runtime=wasmtime`)
  - WASI preview-1 (`--enable-wasi`)
  - `--target wasm` / `--target web` passthrough to the browser host
  - AOT WASM → native (gkgoat1's suggestion in the thread)
  - Configurable `Memory` max pages / per-instance fuel
  - `import attributes` form (`with { type: "wasm" }`)
  - Note in `docs/src/plugins/overview.md` on dylib-vs-WASM trust model

* fix(#76): merge main + close CI gaps (Module field, stable_hash, wasm-host feature gate)

- perry-codegen-arkts: add missing uses_webassembly: false in two
  Module {} initialisers (cargo-test, harmonyos-smoke E0063).
- perry-hir/stable_hash.rs: include uses_webassembly in Module
  destructuring/hash, and add SH arms for the three Expr::WebAssembly*
  variants (compile errors after merging main, which added
  stable_hash.rs).
- perry-runtime: gate `pub mod webassembly` behind a new `wasm-host`
  Cargo feature. The shim TU references `perry_wasm_host_*`; with
  codegen-units = 1, libperry_runtime.a was a single .o and the linker
  pulled the shim in for every binary, so non-wasm programs failed
  with "undefined reference to perry_wasm_host_*" (doc-tests +
  harmonyos-smoke linker errors).
- perry/compile/optimized_libs.rs: push `perry-runtime/wasm-host` into
  cross_features when ctx.needs_wasm_runtime, and fold the flag into
  the perry-auto target-dir hash so a wasm program isn't served a
  cached non-wasm libperry_runtime.a (which lacks js_webassembly_*),
  and vice versa.
- cargo fmt — collapse the long single-line use re-export in
  compile.rs and the .d.ts include_str! in types.rs, plus rustfmt
  reflow inside expr.rs / runtime_decls.rs / lower_decl.rs /
  expr_call.rs / webassembly.rs / perry-wasm-host/lib.rs (lint job).

Merging main also picks up the updated `.github/workflows/security-audit.yml`
(drops `--deny warnings`, ignores the 3 acknowledged RUSTSEC IDs), which
clears the audit failures.

Author: TheHypnoo

Cargo.lock

@@ -46,6 +46,7 @@ members = [
     "crates/perry-ext-streams",
     "crates/perry-ext-fastify",
     "crates/perry-jsruntime",
+    "crates/perry-wasm-host",
     "crates/perry-stdlib",
     "crates/perry-diagnostics",
     "crates/perry-ui",
@@ -119,6 +120,7 @@ default-members = [
     "crates/perry-ext-streams",
     "crates/perry-ext-fastify",
     "crates/perry-jsruntime",
+    "crates/perry-wasm-host",
     "crates/perry-stdlib",
     "crates/perry-diagnostics",
     "crates/perry-ui",
@@ -291,6 +293,7 @@ perry-ext-fastify = { path = "crates/perry-ext-fastify" }
 perry-stdlib = { path = "crates/perry-stdlib" }
 perry-diagnostics = { path = "crates/perry-diagnostics" }
 perry-jsruntime = { path = "crates/perry-jsruntime" }
+perry-wasm-host = { path = "crates/perry-wasm-host" }
 perry-codegen-js = { path = "crates/perry-codegen-js" }
 perry-codegen-swiftui = { path = "crates/perry-codegen-swiftui" }
 perry-codegen-arkts = { path = "crates/perry-codegen-arkts" }

Cargo.toml

@@ -7908,6 +7908,7 @@ mod tests {
             exported_functions: vec![],
             widgets: vec![],
             uses_fetch: false,
+            uses_webassembly: false,
             init_was_unrolled: false,
             extern_funcs: vec![],
         }

crates/perry-codegen-arkts/src/lib.rs

@@ -46,6 +46,7 @@ fn empty_module() -> Module {
         exported_functions: vec![],
         widgets: vec![],
         uses_fetch: false,
+        uses_webassembly: false,
         init_was_unrolled: false,
         extern_funcs: vec![],
     }

crates/perry-codegen-arkts/tests/phase2_full_app_smoke.rs

@@ -5384,6 +5384,89 @@ pub(crate) fn lower_expr(ctx: &mut FnCtx<'_>, expr: &Expr) -> Result<String> {
         // we'd link in; sentinel keeps the compile-pass count up.
         Expr::MathRandom => Ok(ctx.block().call(DOUBLE, "js_math_random", &[])),
 
+        // ── WebAssembly host (issue #76) ──────────────────────────────
+        // The runtime shims (perry-runtime/src/webassembly.rs) handle
+        // bytes extraction, instance handles, and error reporting. The
+        // wasmi engine itself is in the optional `perry-wasm-host`
+        // crate, only linked when the user passes
+        // `--enable-wasm-runtime`. Programs that never call these
+        // builtins never reference the runtime shims, so the linker
+        // dead-strips them and `perry_wasm_host_*` is never demanded.
+        Expr::WebAssemblyValidate(bytes) => {
+            let v = lower_expr(ctx, bytes)?;
+            Ok(ctx
+                .block()
+                .call(DOUBLE, "js_webassembly_validate", &[(DOUBLE, &v)]))
+        }
+        Expr::WebAssemblyInstantiate(bytes) => {
+            let v = lower_expr(ctx, bytes)?;
+            Ok(ctx
+                .block()
+                .call(DOUBLE, "js_webassembly_instantiate", &[(DOUBLE, &v)]))
+        }
+        Expr::WebAssemblyCallExport {
+            instance,
+            name,
+            args,
+        } => {
+            let inst = lower_expr(ctx, instance)?;
+            let name_v = lower_expr(ctx, name)?;
+            let lowered_args: Vec<String> = args
+                .iter()
+                .map(|a| lower_expr(ctx, a))
+                .collect::<Result<Vec<_>>>()?;
+            let blk = ctx.block();
+            match lowered_args.len() {
+                0 => Ok(blk.call(
+                    DOUBLE,
+                    "js_webassembly_call_export_0",
+                    &[(DOUBLE, &inst), (DOUBLE, &name_v)],
+                )),
+                1 => Ok(blk.call(
+                    DOUBLE,
+                    "js_webassembly_call_export_1",
+                    &[
+                        (DOUBLE, &inst),
+                        (DOUBLE, &name_v),
+                        (DOUBLE, &lowered_args[0]),
+                    ],
+                )),
+                2 => Ok(blk.call(
+                    DOUBLE,
+                    "js_webassembly_call_export_2",
+                    &[
+                        (DOUBLE, &inst),
+                        (DOUBLE, &name_v),
+                        (DOUBLE, &lowered_args[0]),
+                        (DOUBLE, &lowered_args[1]),
+                    ],
+                )),
+                3 => Ok(blk.call(
+                    DOUBLE,
+                    "js_webassembly_call_export_3",
+                    &[
+                        (DOUBLE, &inst),
+                        (DOUBLE, &name_v),
+                        (DOUBLE, &lowered_args[0]),
+                        (DOUBLE, &lowered_args[1]),
+                        (DOUBLE, &lowered_args[2]),
+                    ],
+                )),
+                _ => Ok(blk.call(
+                    DOUBLE,
+                    "js_webassembly_call_export_4",
+                    &[
+                        (DOUBLE, &inst),
+                        (DOUBLE, &name_v),
+                        (DOUBLE, &lowered_args[0]),
+                        (DOUBLE, &lowered_args[1]),
+                        (DOUBLE, &lowered_args[2]),
+                        (DOUBLE, &lowered_args[3]),
+                    ],
+                )),
+            }
+        }
+
         // `JSON.stringify(value, replacer, indent)` — full form via
         // runtime `js_json_stringify_full` which handles array/function
         // replacers, indent spaces, circular detection (throws

crates/perry-codegen/src/expr.rs

@@ -435,6 +435,34 @@ pub fn declare_phase_b_strings(module: &mut LlModule) {
     module.declare_function("js_string_compare", I32, &[I64, I64]);
     module.declare_function("js_jsvalue_to_string_radix", I64, &[DOUBLE, I32]);
     module.declare_function("js_math_random", DOUBLE, &[]);
+    // WebAssembly host runtime (issue #76). All take/return NaN-boxed
+    // doubles (JSValues). Implementations live in
+    // `perry-runtime/src/webassembly.rs` and forward to
+    // `perry-wasm-host`'s C ABI; the wasmi engine is only linked when
+    // the user passes `--enable-wasm-runtime`.
+    module.declare_function("js_webassembly_validate", DOUBLE, &[DOUBLE]);
+    module.declare_function("js_webassembly_instantiate", DOUBLE, &[DOUBLE]);
+    module.declare_function("js_webassembly_call_export_0", DOUBLE, &[DOUBLE, DOUBLE]);
+    module.declare_function(
+        "js_webassembly_call_export_1",
+        DOUBLE,
+        &[DOUBLE, DOUBLE, DOUBLE],
+    );
+    module.declare_function(
+        "js_webassembly_call_export_2",
+        DOUBLE,
+        &[DOUBLE, DOUBLE, DOUBLE, DOUBLE],
+    );
+    module.declare_function(
+        "js_webassembly_call_export_3",
+        DOUBLE,
+        &[DOUBLE, DOUBLE, DOUBLE, DOUBLE, DOUBLE],
+    );
+    module.declare_function(
+        "js_webassembly_call_export_4",
+        DOUBLE,
+        &[DOUBLE, DOUBLE, DOUBLE, DOUBLE, DOUBLE, DOUBLE],
+    );
     module.declare_function("js_console_log_spread", VOID, &[I64]);
     module.declare_function("js_console_error_spread", VOID, &[I64]);
     module.declare_function("js_console_warn_spread", VOID, &[I64]);

crates/perry-codegen/src/runtime_decls.rs

@@ -225,6 +225,10 @@ pub struct Module {
     pub widgets: Vec<WidgetDecl>,
     /// Whether this module uses fetch() — requires perry-stdlib for js_fetch_with_options
     pub uses_fetch: bool,
+    /// Whether this module references `WebAssembly.*` (issue #76). Drives
+    /// auto-link of `libperry_wasm_host.a` so users don't have to remember
+    /// `--enable-wasm-runtime` when they actually use the API.
+    pub uses_webassembly: bool,
     /// External FFI function declarations (name, param_types, return_type)
     /// Populated from `declare function` statements with no body.
     pub extern_funcs: Vec<(String, Vec<Type>, Type)>,
@@ -1359,6 +1363,21 @@ pub enum Expr {
 
     /// performance.now() -> number (high-resolution time in ms)
     PerformanceNow,
+
+    // WebAssembly host (issue #76). MVP surface — see
+    // `crates/perry-runtime/src/webassembly.rs` for the FFI shape.
+    /// `WebAssembly.validate(bytes)` -> boolean
+    WebAssemblyValidate(Box<Expr>),
+    /// `WebAssembly.instantiate(bytes)` -> opaque instance handle (Perry
+    /// MVP shape — sync, no Promise, no `{module, instance}` pair).
+    WebAssemblyInstantiate(Box<Expr>),
+    /// `WebAssembly.callExport(instance, name, ...args)` — Perry-specific
+    /// helper for invoking numeric exports (see issue #76 PoC scope).
+    WebAssemblyCallExport {
+        instance: Box<Expr>,
+        name: Box<Expr>,
+        args: Vec<Expr>,
+    },
     /// atob(base64) -> string
     Atob(Box<Expr>),
     /// btoa(string) -> string
@@ -2478,6 +2497,7 @@ impl Module {
             exported_functions: Vec::new(),
             widgets: Vec::new(),
             uses_fetch: false,
+            uses_webassembly: false,
             extern_funcs: Vec::new(),
             init_was_unrolled: false,
         }

crates/perry-hir/src/ir.rs

@@ -182,6 +182,8 @@ pub struct LoweringContext {
     pub(crate) module_native_instances: Vec<(String, String, String)>,
     /// Whether this module uses fetch() — requires perry-stdlib
     pub(crate) uses_fetch: bool,
+    /// Issue #76 — set when any `WebAssembly.*` HIR variant is lowered.
+    pub(crate) uses_webassembly: bool,
     pub(crate) var_hoisted_ids: HashSet<LocalId>,
     /// Shadow index: function name -> index in `functions` Vec (last entry for shadowing)
     pub(crate) functions_index: HashMap<String, usize>,
@@ -222,6 +224,12 @@ pub struct LoweringContext {
     /// HIR variants which read the runtime's thread-local exec metadata.
     pub(crate) regex_exec_locals: HashSet<String>,
     pub(crate) proxy_locals: HashSet<String>,
+    /// Issue #76 — locals known to hold a WebAssembly instance handle (i.e.
+    /// `const x = WebAssembly.instantiate(...)`). Used to route
+    /// `x.exports.<method>(...)` to `Expr::WebAssemblyCallExport` only when
+    /// the receiver is a tracked instance, avoiding false matches against
+    /// CJS-style `module.exports.foo()` patterns.
+    pub(crate) wasm_instance_locals: HashSet<String>,
     pub(crate) proxy_revoke_locals: HashMap<String, String>,
     /// For `const p = new Proxy(ClassName, handler)`, record the class name
     /// so `new p(args)` can fold to `new ClassName(args)` (pragmatic — lets
@@ -344,6 +352,7 @@ impl LoweringContext {
             current_namespace: None,
             module_native_instances: Vec::new(),
             uses_fetch: false,
+            uses_webassembly: false,
             var_hoisted_ids: HashSet::new(),
             functions_index: HashMap::new(),
             classes_index: HashMap::new(),
@@ -358,6 +367,7 @@ impl LoweringContext {
             iterator_func_for_class: std::collections::HashMap::new(),
             regex_exec_locals: HashSet::new(),
             proxy_locals: HashSet::new(),
+            wasm_instance_locals: HashSet::new(),
             proxy_revoke_locals: HashMap::new(),
             proxy_target_classes: HashMap::new(),
             class_expr_aliases: HashMap::new(),
@@ -2225,6 +2235,7 @@ pub fn lower_module_full(
     }
 
     module.uses_fetch = ctx.uses_fetch;
+    module.uses_webassembly = ctx.uses_webassembly;
     module.extern_funcs = ctx.extern_func_types.clone();
 
     // Post-pass: widen `mutable_captures` across sibling closures. When two
@@ -7277,6 +7288,7 @@ pub(crate) fn lower_expr(ctx: &mut LoweringContext, expr: &ast::Expr) -> Result<
                     && name != "atob"
                     && name != "btoa"
                     && name != "BigInt"
+                    && name != "WebAssembly"
                 {
                     eprintln!(
                         "  Warning: unknown identifier '{}' — assuming global; member access will dispatch by name at runtime, bare reads lower to 0",