dommy-js-wasmtime 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5c63d21b5f68aa52f4ac026e1d7a3370c6d4b277c4b78bfd32731b092a0be375
+  data.tar.gz: ceb394faaa0b7783e7398ee71d7c1983a7fbbfd9e72d3463cfe5c31070ad1b26
+SHA512:
+  metadata.gz: a5e28dd35f810a1d66ec4c67f9de8ba748dc9e8dba0bfeb17bd7f296d869732902e67586ffd12905e040f6ee34b68fef462f4a7d5d3024f7cb8867b4c8d73f0e
+  data.tar.gz: 54fc08f9e8ab4e2bf1b78676fb5ac4be72a61b8812619f4c794fca0f688247e0d1d707eba9bb9006277e1b9de218d04189eecfcaabaafd443f67d31163e23574

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [Unreleased]
+
+- Initial release.
+- `Dommy::Js::Wasmtime::VM` — a wasmtime-rb host for mruby-wasm-js builds (the
+  Lilac runtime): implements the 25-function `js.*` handle-table interop ABI and
+  the WASI preview1 surface, routing JS interop to a pluggable engine.
+- `Dommy::Js::Wasmtime::Engines::Quickjs` — default engine; a QuickJS VM bound to
+  a Dommy DOM (via `dommy-js-quickjs`), giving the wasm a real JS world
+  (promises/await/fetch, full marshalling).
+- `Dommy::Js::Wasmtime.boot` — convenience loader: build the VM over a Dommy DOM,
+  seed the JS world, load mruby sources, and eval an `entrypoint` (e.g.
+  `Lilac.start`).
+- Minitest suite: engine unit tests + VM integration tests (against a vendored
+  mruby-wasm-js fixture), plus a cross-check against lilac's own wasm spec suite.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 TAKAHASHI Masayoshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,99 @@
+# dommy-js-wasmtime
+
+[![CI](https://github.com/takahashim/dommy-js-wasmtime/actions/workflows/ci.yml/badge.svg)](https://github.com/takahashim/dommy-js-wasmtime/actions/workflows/ci.yml)
+
+Run an **mruby-wasm-js** build on
+[wasmtime-rb](https://github.com/bytecodealliance/wasmtime-rb), bridged to a
+[Dommy](https://github.com/takahashim/dommy) DOM — no browser, no Node, no
+happy-dom. The [Lilac](https://github.com/takahashim/lilac) component runtime is
+the primary example, but the gem itself doesn't depend on Lilac: it targets the
+generic mruby-wasm-js host ABI.
+
+It is the wasmtime sibling of `dommy-js-quickjs`. Where `dommy-js-quickjs` runs
+*JavaScript* against Dommy, this gem runs *mruby* (inside wasm, on wasmtime) and
+serves its JS interop from a real JS world:
+
+```
+  mruby (app.wasm)  ──js.* handle ABI──▶  VM (wasmtime host)
+                                            │
+                                            ▼  Engines::Quickjs
+                                     QuickJS globalThis  ──dommy-js-quickjs──▶  Dommy DOM
+```
+
+So `JS.global` is a real `globalThis`, promises / `await` / `fetch` work, and the
+same DOM the wasm mutates is inspectable from Ruby via Dommy's API.
+
+## How it works
+
+The wasm imports two modules; this gem implements both in pure Ruby:
+
+- **`js`** — the 25-function handle-table interop ABI (`js_global`, `js_get`,
+  `js_call`, `js_new`, `js_make_callback`, …). Values cross as small integer
+  handles; the VM stores the Ruby/JS objects and routes property/method access
+  through the bridge ABI (`__js_get__` / `__js_set__` / `__js_call__` /
+  `__js_new__`). The default engine (`Engines::Quickjs`) backs each handle with a
+  live QuickJS value (`JsRef`).
+- **`wasi_snapshot_preview1`** — wasmtime's bundled WASI preview1, with `fd_write`
+  shadowed to capture mruby stdout/stderr.
+
+mruby-wasm-js builds use the WebAssembly exception-handling proposal (mruby's
+longjmp); wasmtime enables it via `Engine.new(wasm_exceptions: true)`.
+
+## Usage
+
+```ruby
+require "dommy"
+require "dommy/js/wasmtime"
+
+vm = Dommy::Js::Wasmtime.boot(
+  wasm: "build/app.wasm",
+  html: File.read("index.html"),
+  sources: Dir["lib/*.rb"],          # mruby source files, loaded in order
+  entrypoint: "Lilac.start",         # app boot call after sources load (or nil)
+) do |engine|
+  engine.eval(<<~JS)                 # seed the JS world (e.g. a fetch fixture)
+    globalThis.fetch = async (u) => new Response(DATA_JSON, { status: 200 });
+  JS
+end
+
+vm.document.query_selector(".app")   # the DOM the mruby app rendered
+```
+
+`boot` builds the VM, runs `_initialize`, optionally seeds the JS world, loads the
+mruby sources, and evals `entrypoint` (e.g. `Lilac.start` to mount components).
+After each `eval`, the event loop is driven to quiescence so fibers suspended on
+`.await` settle.
+
+For lower-level use, drive the VM directly — it has no app-framework knowledge:
+
+```ruby
+vm = Dommy::Js::Wasmtime::VM.new(wasm: "build/app.wasm")
+vm.eval('JS.global[:document].call(:querySelector, "h1")')
+vm.stdout
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake        # runs the test suite + RuboCop
+bundle exec rake test
+```
+
+The suite has two layers: engine unit tests (`Engines::Quickjs`, no wasm —
+marshalling, the JsRef bridge ABI, callbacks, the event-loop drive) and VM
+integration tests that run real mruby through the `js.*` bridge against
+QuickJS+Dommy (DOM read/write, callback round-trips, `await`, JS-error capture).
+
+The integration tests need an mruby-wasm-js `.wasm` with the compiler
+(`js_eval_handle`). A representative build (lilac-full) is vendored at
+`test/fixtures/mruby-wasm-js.wasm`; point `DOMMY_JS_WASMTIME_TEST_WASM` at another
+build to override. The tests use only mruby + the `JS` module, not Lilac's
+component API.
+
+## Status
+
+Extracted from lilac's reference host (`test/ruby_spec/mruby_wasm.rb` +
+`quickjs_bridge.rb`); additionally cross-checked by running lilac's own wasm spec
+suite through this VM and diffing per-spec results against the reference host
+(identical).

data/lib/dommy/js/wasmtime/engines/quickjs.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "dommy"
+require "dommy/js/quickjs"
+
+module Dommy
+  module Js
+    module Wasmtime
+      module Engines
+        # Real-JS engine backing the wasmtime host's `js.*` bridge.
+        #
+        # mruby-in-wasm reaches the host through ~25 `js_*` imports that operate on
+        # opaque JS *handles* (js_eval / js_global / js_get / js_set / js_call /
+        # js_new / js_make_callback / …). In the browser those go to V8; here they
+        # go to a QuickJS VM bound to a Dommy DOM (dommy-js-quickjs's WasmBridge),
+        # so the mruby inner loop runs the *same* JavaScript a browser would.
+        #
+        # One global JS world: QuickJS owns globalThis, Dommy's window/document are
+        # installed into it, and the guest's `JS.global` IS quickjs globalThis — so
+        # a fetch stub installed with `engine.eval("globalThis.fetch = …")` and the
+        # fetch Fetchy calls are the same function (no split brain).
+        #
+        # Every JS value crosses as a JsRef implementing the bridge ABI
+        # (__js_get__/__js_set__/__js_call__/__js_new__), so the VM's duck-typed
+        # dispatch drives it unchanged.
+        #
+        # Extracted from lilac's reference host (test/ruby_spec/quickjs_bridge.rb).
+        class Quickjs
+          # A handle to a live JS value in the quickjs VM, exposing the same bridge
+          # ABI Dommy objects do.
+          class JsRef
+            attr_reader :jsvalue
+
+            def initialize(bridge, jsvalue)
+              @bridge = bridge
+              @jsvalue = jsvalue
+            end
+
+            def __js_get__(key)
+              @bridge.wrap_result(@bridge.wb.get(@jsvalue, key))
+            end
+
+            def __js_set__(key, value)
+              @bridge.wb.set(@jsvalue, key, @bridge.unwrap_arg(value))
+              value
+            end
+
+            def __js_call__(method, args)
+              @bridge.wrap_result(@bridge.wb.call(@jsvalue, method, args.map { |a| @bridge.unwrap_arg(a) }))
+            end
+
+            def __js_new__(args)
+              @bridge.wrap_result(@bridge.wb.construct(@jsvalue, args.map { |a| @bridge.unwrap_arg(a) }))
+            end
+          end
+
+          JSValue = Dommy::Js::Quickjs::WasmBridge::JSValue
+
+          attr_reader :wb, :global, :window
+
+          # @param invoke [#call] invoke.(callback_id, ruby_args) -> guest return
+          #   value; the VM passes its #invoke_callback so JS callbacks route into
+          #   the wasm's js_invoke_proc.
+          # @param window [Dommy::Window] the DOM to render into (a fresh one by default)
+          def initialize(invoke:, window: Dommy.new_window)
+            @window = window
+            @runtime = Dommy::Js::Quickjs::Runtime.new
+            @runtime.install_window(@window)
+            @runtime.install_browser_globals
+            @runtime.define_host_object("document", @window.document)
+            @wb = @runtime.wasm_bridge
+            @wb.on_invoke do |callback_id, packed_args|
+              ruby_args = packed_args.map { |pa| wrap_result(@wb.unpack(pa)) }
+              result = invoke.call(callback_id, ruby_args)
+              @wb.pack(unwrap_arg(result))
+            end
+            @global = wrap_result(@wb.global_ref)
+          end
+
+          def document = @window.document
+
+          # Evaluate real JS source (the JS.eval_javascript escape hatch + the
+          # bridge's js_eval import).
+          def eval(src)
+            wrap_result(@wb.eval_js(src))
+          end
+
+          # A JS function that calls back into the guest's callback table by id.
+          def make_callback(callback_id)
+            wrap_result(@wb.make_callback(callback_id))
+          end
+
+          # Drive the event loop to quiescence (WHATWG-ordered): drain microtasks,
+          # advance Dommy's deterministic scheduler to its next timer, repeat.
+          def run_until_idle
+            @runtime.run_until_idle
+          end
+
+          def on_log(&) = @runtime.on_log(&)
+
+          def typeof(value)
+            return @wb.typeof(value.jsvalue) if value.is_a?(JsRef)
+
+            case value
+            when nil then "object" # typeof null === "object"
+            when Integer, Float then "number"
+            when String then "string"
+            when true, false then "boolean"
+            else "object"
+            end
+          end
+
+          def to_string(value)
+            return @wb.to_string(value.jsvalue) if value.is_a?(JsRef)
+
+            value.to_s
+          end
+
+          def strict_equal(a, b)
+            return @wb.strict_equal(a.jsvalue, b.jsvalue) if a.is_a?(JsRef) && b.is_a?(JsRef)
+
+            a == b
+          end
+
+          def instanceof(value, ctor)
+            return false unless value.is_a?(JsRef) && ctor.is_a?(JsRef)
+
+            @wb.instance_of?(value.jsvalue, ctor.jsvalue)
+          end
+
+          # WasmBridge value (primitive | JSValue) -> handle value (primitive | JsRef).
+          def wrap_result(value)
+            value.is_a?(JSValue) ? JsRef.new(self, value) : value
+          end
+
+          # Handle value (primitive | JsRef | Array | Hash) -> WasmBridge arg.
+          def unwrap_arg(value)
+            case value
+            when JsRef then value.jsvalue
+            when Array then value.map { |e| unwrap_arg(e) }
+            when Hash then value.transform_values { |e| unwrap_arg(e) }
+            else value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dommy/js/wasmtime/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    module Wasmtime
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/dommy/js/wasmtime/vm.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require "wasmtime"
+require "json"
+require "dommy"
+
+module Dommy
+  module Js
+    module Wasmtime
+      # Raised when mruby raises an unhandled exception during eval / load_bytecode.
+      class RubyError < StandardError; end
+
+      # A wasmtime-rb host for an mruby-wasm-js build (e.g. the Lilac runtime). It
+      # implements the two import modules the wasm needs:
+      #
+      #   - `js`                       the 25-function handle-table interop ABI,
+      #                                routed to a pluggable JS engine (Engines::Quickjs
+      #                                by default) whose values implement the bridge
+      #                                ABI (__js_get__/__js_set__/__js_call__/__js_new__)
+      #   - `wasi_snapshot_preview1`   wasmtime's bundled WASI preview1, with fd_write
+      #                                shadowed to capture mruby stdout/stderr
+      #
+      # Extracted from lilac's reference host (test/ruby_spec/mruby_wasm.rb).
+      class VM
+        attr_reader :engine, :wasm_path
+
+        # @param wasm   [String] path to the mruby-wasm-js .wasm (e.g. lilac.wasm)
+        # @param engine [#global,#eval,#make_callback,#run_until_idle,…] the JS
+        #   engine backing the bridge. Defaults to a QuickJS VM bound to a fresh
+        #   Dommy window (real JS over a real DOM).
+        def initialize(wasm:, engine: nil)
+          @wasm_path = wasm.to_s
+          @engine = engine || default_engine
+          @stdout_buf = String.new(encoding: Encoding::BINARY)
+          @stderr_buf = String.new(encoding: Encoding::BINARY)
+          wire_console!
+
+          # Handle table. id 0 = undefined/null sentinel; id 1 = the JS global
+          # (engine.global). User values (primitives, JsRefs, Ruby Hash/Array)
+          # live at ids >= 100.
+          @handles = { 0 => nil, 1 => @engine.global }
+          @next_handle = 100
+          # A JS-side exception captured during js_call (a host callback can't
+          # raise out of a wasmtime host function — it would unwind the wasm
+          # runtime), handed back to mruby via the js_take_error import so it
+          # surfaces as JS::Error instead of crashing the host.
+          @pending_error = 0
+          boot!
+        end
+
+        # The Dommy document/window the engine renders into — the same DOM the wasm
+        # runtime mutates. Host-side tests drive and inspect it via Dommy's Ruby API.
+        def document = @engine.document
+        def window = @engine.window
+
+        # Evaluate mruby source. Returns mruby's exit code (0 on success, 1 on
+        # error, 2 if the compiler is absent). After the eval, drives the event
+        # loop so fibers suspended on `.await` settle (the Ruby-host equivalent of
+        # the browser/Node event loop unwinding the stack).
+        def eval(source)
+          handle = store_handle(source.b)
+          rc = @js_eval_handle.call(handle, 0, 0)
+          drain_async!
+          rc
+        ensure
+          @handles.delete(handle) if handle
+        end
+
+        # Like #eval but raises RubyError on a non-zero exit code.
+        def eval!(source)
+          rc = eval(source)
+          raise RubyError, "mruby eval failed (rc=#{rc})#{stderr_tail}" unless rc.zero?
+
+          rc
+        end
+
+        # Load pre-compiled mrbc bytecode. Bytes flow in via the handle table as an
+        # array-like (js_load_irep_handle reads length + indexed bytes).
+        def load_bytecode(bytes)
+          handle = store_handle(bytes.bytes)
+          rc = @js_load_irep_handle.call(handle)
+          drain_async!
+          rc
+        ensure
+          @handles.delete(handle) if handle
+        end
+
+        # Drive the engine's event loop to quiescence.
+        def drain_async! = @engine.run_until_idle
+
+        # Fire an mruby block registered via `JS.callback`. `args` are Ruby values
+        # (already unwrapped by the engine); they cross as a single handle to the
+        # args array.
+        def invoke_callback(callback_id, args)
+          args_handle = store_handle(args)
+          result_handle = @js_invoke_proc.call(callback_id, args_handle)
+          @handles[result_handle]
+        ensure
+          @handles.delete(args_handle) if args_handle
+          @handles.delete(result_handle) if result_handle && result_handle >= 100
+        end
+
+        # Captured stdout/stderr since the last read (clears the buffer).
+        def stdout
+          out = @stdout_buf
+          @stdout_buf = String.new(encoding: Encoding::BINARY)
+          out
+        end
+
+        def stderr
+          out = @stderr_buf
+          @stderr_buf = String.new(encoding: Encoding::BINARY)
+          out
+        end
+
+        private
+
+        def default_engine
+          require_relative "engines/quickjs"
+          Engines::Quickjs.new(invoke: method(:invoke_callback))
+        end
+
+        # mruby routes $stdout/$stderr through the JS console (mruby-wasm-js's
+        # z_console_io), so puts/warn reach us via the engine's log hook, not WASI
+        # fd_write. Severity error/warning → stderr.
+        def wire_console!
+          @engine.on_log do |log|
+            buf = %i[error warning].include?(log.severity) ? @stderr_buf : @stdout_buf
+            buf << log.to_s << "\n"
+          end
+        end
+
+        def boot!
+          @wt_engine = ::Wasmtime::Engine.new(wasm_exceptions: true)
+          @module = ::Wasmtime::Module.from_file(@wt_engine, @wasm_path)
+
+          linker = ::Wasmtime::Linker.new(@wt_engine)
+          register_js!(linker)
+          register_wasi!(linker)
+
+          @store = ::Wasmtime::Store.new(@wt_engine, wasi_p1_config: ::Wasmtime::WasiConfig.new)
+          @instance = linker.instantiate(@store, @module)
+
+          init = @instance.export("_initialize")&.to_func
+          init&.call
+
+          @js_invoke_proc = @instance.export("js_invoke_proc")&.to_func
+          @js_eval_handle = @instance.export("js_eval_handle")&.to_func
+          @js_load_irep_handle = @instance.export("js_load_irep_handle")&.to_func
+          raise "wasm is missing js_eval_handle export" unless @js_eval_handle
+        end
+
+        # ----- handle table --------------------------------------------------
+
+        def store_handle(value)
+          id = @next_handle
+          @handles[id] = value
+          @next_handle += 1
+          id
+        end
+
+        def handle_for(value)
+          value.nil? ? 0 : store_handle(value)
+        end
+
+        # ----- js.* bridge (25 functions) ------------------------------------
+
+        def register_js!(linker)
+          define = ->(name, params, results, &body) { linker.func_new("js", name, params, results, &body) }
+
+          define.call("js_eval", %i[i32 i32], [:i32]) do |c, p, l|
+            handle_for(@engine.eval(read_str(c, p, l).strip))
+          end
+          define.call("js_global", [], [:i32]) { |_c| 1 }
+          define.call("js_release", [:i32], []) { |_c, _h| nil } # accumulate; see reference note
+
+          define.call("js_get", %i[i32 i32 i32], [:i32]) do |c, h, p, l|
+            obj = @handles[h]
+            key = read_str(c, p, l)
+            handle_for(host_get(obj, key))
+          end
+
+          define.call("js_set", %i[i32 i32 i32 i32], []) do |c, h, p, l, v|
+            host_set(@handles[h], read_str(c, p, l), @handles[v])
+            nil
+          end
+
+          define.call("js_call", %i[i32 i32 i32 i32 i32], [:i32]) do |c, h, mp, ml, ap, ac|
+            obj = @handles[h]
+            method = read_str(c, mp, ml)
+            args = read_handle_args(c, ap, ac)
+            begin
+              handle_for(host_call(obj, method, args))
+            rescue StandardError => e
+              # Surface to mruby via js_take_error on the next bridge hit (the
+              # wasm throws JS::Error); we can't raise out of a host callback.
+              @pending_error = store_handle("#{e.class}: #{e.message}")
+              0
+            end
+          end
+
+          define.call("js_new", %i[i32 i32 i32], [:i32]) do |c, ctor, ap, ac|
+            obj = @handles[ctor]
+            args = read_handle_args(c, ap, ac)
+            handle_for(obj.respond_to?(:__js_new__) ? obj.__js_new__(args) : nil)
+          end
+
+          define.call("js_to_string_len", [:i32], [:i32]) { |_c, h| string_value(@handles[h]).bytesize }
+          define.call("js_to_string_copy", %i[i32 i32 i32], []) do |c, h, ptr, len|
+            value = string_value(@handles[h])
+            c.export("memory").to_memory.write(ptr, value.byteslice(0, len)) if len.positive?
+            nil
+          end
+          define.call("js_from_string", %i[i32 i32], [:i32]) { |c, p, l| store_handle(read_str(c, p, l)) }
+          define.call("js_to_int", [:i32], [:i32]) { |_c, h| Integer(@handles[h] || 0) }
+          define.call("js_from_int", [:i32], [:i32]) { |_c, n| store_handle(n) }
+          define.call("js_to_float", [:i32], [:f64]) { |_c, h| Float(@handles[h] || 0.0) }
+          define.call("js_from_float", [:f64], [:i32]) { |_c, x| store_handle(x) }
+          define.call("js_is_null", [:i32], [:i32]) { |_c, h| @handles[h].nil? ? 1 : 0 }
+          define.call("js_strict_equal", %i[i32 i32], [:i32]) do |_c, a, b|
+            @engine.strict_equal(@handles[a], @handles[b]) ? 1 : 0
+          end
+          define.call("js_typeof_len", [:i32], [:i32]) { |_c, h| @engine.typeof(@handles[h]).bytesize }
+          define.call("js_typeof_copy", %i[i32 i32 i32], []) do |c, h, p, l|
+            c.export("memory").to_memory.write(p, @engine.typeof(@handles[h]).byteslice(0, l))
+            nil
+          end
+          define.call("js_inspect_len", [:i32], [:i32]) { |_c, h| inspect_value(@handles[h]).bytesize }
+          define.call("js_inspect_copy", %i[i32 i32 i32], []) do |c, h, p, l|
+            c.export("memory").to_memory.write(p, inspect_value(@handles[h]).byteslice(0, l))
+            nil
+          end
+          define.call("js_instanceof", %i[i32 i32], [:i32]) do |_c, h, ctor|
+            @engine.instanceof(@handles[h], @handles[ctor]) ? 1 : 0
+          end
+          define.call("js_make_callback", [:i32], [:i32]) do |_c, callback_id|
+            store_handle(@engine.make_callback(callback_id))
+          end
+          define.call("js_handle_count", [], [:i32]) { |_c| @handles.size }
+          define.call("js_clone", [:i32], [:i32]) { |_c, h| h }
+          define.call("js_take_error", [], [:i32]) do |_c|
+            err = @pending_error
+            @pending_error = 0
+            err
+          end
+        end
+
+        # Property/method routing. JS values cross as engine refs (or Dommy
+        # objects) implementing the bridge ABI; plain Ruby Array/Hash that cross
+        # (callback args, host results) get array-like / hash-like access.
+        def host_get(obj, key)
+          return obj.__js_get__(key) if obj.respond_to?(:__js_get__)
+
+          case obj
+          when Array
+            return obj.size if key == "length"
+
+            (idx = Integer(key, exception: false)) ? obj[idx] : nil
+          when Hash
+            obj[key]
+          end
+        end
+
+        def host_set(obj, key, value)
+          return obj.__js_set__(key, value) if obj.respond_to?(:__js_set__)
+
+          case obj
+          when Array then (idx = Integer(key, exception: false)) && (obj[idx] = value)
+          when Hash then obj[key] = value
+          end
+          nil
+        end
+
+        def host_call(obj, method, args)
+          return obj.__js_call__(method, args) if obj.respond_to?(:__js_call__)
+          if obj.is_a?(Array) && method == "push"
+            return (args.each { |a| obj.push(a) }
+                    obj.size)
+          end
+
+          nil
+        end
+
+        # ----- WASI ----------------------------------------------------------
+
+        def register_wasi!(linker)
+          ::Wasmtime::WASI::P1.add_to_linker_sync(linker)
+          linker.allow_shadowing = true
+          linker.func_new("wasi_snapshot_preview1", "fd_write", %i[i32 i32 i32 i32],
+                          [:i32]) do |c, fd, iovs, n, nwritten|
+            mem = c.export("memory").to_memory
+            buf = fd == 2 ? @stderr_buf : @stdout_buf
+            total = 0
+            n.times do |i|
+              base = iovs + (i * 8)
+              ptr = mem.read(base, 4).unpack1("l<")
+              len = mem.read(base + 4, 4).unpack1("l<")
+              buf << mem.read(ptr, len) if len.positive?
+              total += len
+            end
+            mem.write(nwritten, [total].pack("l<"))
+            0
+          end
+        end
+
+        # ----- memory + value helpers ----------------------------------------
+
+        def read_str(caller, ptr, len)
+          return "" if len <= 0
+
+          caller.export("memory").to_memory.read(ptr, len).force_encoding("UTF-8")
+        end
+
+        def read_handle_args(caller, ptr, count)
+          return [] if count.zero?
+
+          caller.export("memory").to_memory.read(ptr, count * 4).unpack("l<*").map { |h| @handles[h] }
+        end
+
+        def string_value(value)
+          case value
+          when String then value
+          when true then "true"
+          when false then "false"
+          when Integer, Float then value.to_s
+          when nil then ""
+          else @engine.to_string(value)
+          end
+        end
+
+        def inspect_value(value)
+          @engine.to_string(value)
+        rescue StandardError
+          value.inspect
+        end
+
+        def stderr_tail
+          tail = @stderr_buf.dup.force_encoding("UTF-8")
+          tail.empty? ? "" : "\n#{tail}"
+        end
+      end
+    end
+  end
+end

data/lib/dommy/js/wasmtime.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "dommy"
+
+require_relative "wasmtime/version"
+require_relative "wasmtime/vm"
+
+module Dommy
+  module Js
+    # A wasmtime-rb host for mruby-wasm-js builds, bridged to a Dommy DOM. The
+    # wasmtime sibling of dommy-js-quickjs: it runs *mruby* (inside wasm on
+    # wasmtime) and serves its `js.*` interop from a real JS world — a QuickJS VM
+    # bound to Dommy (dommy-js-quickjs) — so `JS.global` is real globalThis,
+    # promises/await/fetch work, and the same DOM the wasm mutates is inspectable
+    # from Ruby. Any mruby-wasm-js build works; the Lilac component runtime is the
+    # primary example.
+    #
+    #   require "dommy"
+    #   require "dommy/js/wasmtime"
+    #
+    #   vm = Dommy::Js::Wasmtime.boot(
+    #     wasm: "build/app.wasm",
+    #     html: File.read("index.html"),
+    #     sources: %w[lib/foo.rb lib/bar.rb …],       # mruby source files
+    #     entrypoint: "Lilac.start",                  # app boot call (or nil)
+    #   ) do |engine|
+    #     engine.eval(<<~JS)                          # seed the JS world
+    #       globalThis.fetch = async (u) => new Response(DATA_JSON, {…});
+    #     JS
+    #   end
+    #   vm.document.query_selector(".app")            # driven by the mruby app
+    module Wasmtime
+      class Error < StandardError; end
+
+      # Build a VM over a Dommy DOM, optionally seed the JS world (fetch stub,
+      # globals), load the mruby source files, and run an app boot call — the Ruby
+      # equivalent of a browser bootstrap script.
+      #
+      # @param wasm       [String] path to the mruby-wasm-js .wasm
+      # @param html       [String, nil] HTML to parse into the window's document
+      # @param window     [Dommy::Window, nil] explicit window (overrides html)
+      # @param sources    [Array<String>] mruby source file paths (loaded in order)
+      # @param entrypoint [String, nil] mruby expression to eval after sources
+      #   load (e.g. "Lilac.start" to mount components); nil to skip
+      # @yield [engine] optional hook to seed the JS world before sources load
+      # @return [VM]
+      def self.boot(wasm:, html: nil, window: nil, sources: [], entrypoint: nil)
+        require_relative "wasmtime/engines/quickjs"
+        win = window || Dommy.parse(html.to_s)
+        vm = nil
+        engine = Engines::Quickjs.new(invoke: ->(id, args) { vm.invoke_callback(id, args) }, window: win)
+        vm = VM.new(wasm: wasm, engine: engine)
+        yield engine if block_given?
+        Array(sources).each { |path| vm.eval!(::File.read(path.to_s)) }
+        vm.eval!(entrypoint) if entrypoint
+        vm
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: dommy-js-wasmtime
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- TAKAHASHI Masayoshi
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dommy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: dommy-js-quickjs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: wasmtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 45.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 45.0.0
+description: A wasmtime-rb host for mruby-wasm-js builds (the Lilac component runtime
+  is the primary example). It reimplements the mruby-wasm-js `js.*` handle-table ABI
+  and the WASI preview1 surface in pure Ruby, routing JS interop into Dommy's `__js_get__/__js_set__/__js_call__/__js_new__`
+  bridge protocol. The wasmtime sibling of dommy-js-quickjs — but instead of running
+  JavaScript it drives Dommy from mruby running inside wasm.
+email:
+- takahashimm@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/dommy/js/wasmtime.rb
+- lib/dommy/js/wasmtime/engines/quickjs.rb
+- lib/dommy/js/wasmtime/version.rb
+- lib/dommy/js/wasmtime/vm.rb
+homepage: https://github.com/takahashim/dommy-js-wasmtime
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/takahashim/dommy-js-wasmtime
+  changelog_uri: https://github.com/takahashim/dommy-js-wasmtime/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Run mruby-wasm-js builds on wasmtime-rb, bridged to a Dommy DOM
+test_files: []