dommy-js-quickjs 0.1.0

data/lib/dommy/js/quickjs/backend.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "quickjs"
+
+module Dommy
+  module Js
+    module Quickjs
+      # Binds HostBridge's abstract backend contract to the `quickjs` gem.
+      class Backend
+        # The gem's default eval timeout is 100ms, which interrupts large
+        # synchronous bridge loops (every property crossing is a Ruby call).
+        DEFAULT_TIMEOUT_MSEC = 60_000
+
+        def initialize(**vm_opts)
+          vm_opts = {timeout_msec: DEFAULT_TIMEOUT_MSEC}.merge(vm_opts)
+          @vm = ::Quickjs::VM.new(**vm_opts)
+        end
+
+        def eval(js)
+          @vm.eval_code(js, async: false)
+        end
+
+        # Async eval: the gem awaits the top-level result and drains the
+        # microtask queue, so JS `await`/Promises resolve before returning.
+        def eval_awaited(js)
+          @vm.eval_code(js, async: true)
+        end
+
+        def define_host_function(name, &block)
+          @vm.define_function(name, &block)
+        end
+
+        def call_js(path, *args)
+          @vm.call(path, *args)
+        end
+
+        def drain_microtasks
+          @vm.drain_jobs!
+        end
+
+        # Register a handler for promise rejections that reach the microtask
+        # queue with no `.catch` — frameworks (Turbo, …) often swallow these,
+        # so surfacing them is essential for diagnosing failures.
+        def on_unhandled_rejection(&block)
+          @vm.on_unhandled_rejection(&block)
+        end
+
+        # Register a handler for console.(log|info|debug|warn|error). The block
+        # receives a log object (#severity / #to_s / #raw).
+        def on_log(&block)
+          @vm.on_log(&block)
+        end
+
+        def run_gc
+          @vm.gc!
+        end
+
+        def dispose
+          @vm.dispose!
+        end
+      end
+    end
+  end
+end

data/lib/dommy/js/quickjs/capybara.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "capybara/dommy"
+require_relative "../quickjs"
+
+module Dommy
+  module Js
+    module Quickjs
+      # Opt-in Capybara integration. Requiring this file enables JS execution on
+      # Capybara::Dommy::Driver (via install_capybara! below), so execute_script /
+      # evaluate_script run against the current Dommy document through a QuickJS
+      # Runtime. Without this require, capybara-dommy stays JS-free (its default).
+      module CapybaraDriver
+        def execute_script(script, *_args)
+          dommy_js_runtime.execute(script)
+          nil
+        end
+
+        def evaluate_script(script, *_args)
+          decode_for_capybara(dommy_js_runtime.evaluate(script))
+        end
+
+        # No real async loop; evaluate synchronously. Sufficient for scripts
+        # that resolve immediately (the common Capybara case).
+        def evaluate_async_script(script, *args)
+          evaluate_script(script, *args)
+        end
+
+        private
+
+        # One Runtime per document. Rebuilt when navigation swaps the document
+        # so JS always sees the current page (and the old VM is released).
+        def dommy_js_runtime
+          doc = document
+          unless defined?(@dommy_js_doc) && @dommy_js_doc.equal?(doc)
+            @dommy_js_runtime&.dispose
+            @dommy_js_runtime = Runtime.new
+            @dommy_js_runtime.define_host_object("document", doc)
+            view = doc.default_view
+            @dommy_js_runtime.install_window(view) if view
+            @dommy_js_doc = doc
+          end
+          @dommy_js_runtime
+        end
+
+        # Map an evaluate() result to what Capybara expects:
+        #   - Array            -> recurse (so element collections wrap per item)
+        #   - JS undefined      -> nil
+        #   - Dommy::Element    -> Capybara::Dommy::Node (covers HTML/SVG subclasses)
+        #   - other bridge obj  -> nil (Document/Text/Comment/Fragment/NodeList/
+        #                          Window have no Capybara representation; a browser
+        #                          likewise returns non-serializable values as null)
+        #   - primitive/Hash    -> as-is
+        def decode_for_capybara(value)
+          case value
+          when Array
+            value.map { |element| decode_for_capybara(element) }
+          when ::Quickjs::Value::UNDEFINED
+            nil
+          when ::Dommy::Element
+            ::Capybara::Dommy::Node.new(self, value)
+          else
+            value.respond_to?(:__js_get__) ? nil : value
+          end
+        end
+      end
+
+      # Idempotently prepend JS-execution support onto Capybara::Dommy::Driver.
+      # Safe to call multiple times; only prepends once. Called on require, but
+      # exposed so integration can be enabled/controlled explicitly (e.g. tests).
+      def self.install_capybara!
+        return if ::Capybara::Dommy::Driver.ancestors.include?(CapybaraDriver)
+
+        ::Capybara::Dommy::Driver.prepend(CapybaraDriver)
+      end
+    end
+  end
+end
+
+Dommy::Js::Quickjs.install_capybara!

data/lib/dommy/js/quickjs/runtime.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    module Quickjs
+      # Public entry point: a JS runtime that can drive a Dommy DOM.
+      #
+      #   rt = Dommy::Js::Quickjs::Runtime.new
+      #   rt.define_host_object("document", win.document)
+      #   rt.evaluate('document.querySelector("h1").textContent')  #=> "..."
+      #
+      # Wires the QuickJS Backend to the engine-agnostic HostBridge, seeded with
+      # the Dommy method manifest.
+      class Runtime
+        def initialize(**vm_opts)
+          @backend = Backend.new(**vm_opts)
+          @bridge = Dommy::Js::HostBridge.new(@backend)
+        end
+
+        def define_host_object(name, obj)
+          @bridge.define_host_object(name, obj)
+        end
+
+        # Inject the Dommy window and alias the bare browser timer globals to it,
+        # so `setTimeout(fn, ms)` routes into Dommy's deterministic scheduler.
+        # Drive callbacks with `win.scheduler.advance_time(ms)`. `window.setTimeout`
+        # already works via the Window manifest; this also wires the unqualified
+        # globals browsers expose.
+        def install_window(win)
+          @window = win
+          define_host_object("window", win)
+          @bridge.window = win
+          @backend.eval(<<~JS)
+            globalThis.setTimeout = (fn, delay) => window.setTimeout(fn, delay);
+            globalThis.clearTimeout = (id) => window.clearTimeout(id);
+            globalThis.setInterval = (fn, delay) => window.setInterval(fn, delay);
+            globalThis.clearInterval = (id) => window.clearInterval(id);
+            globalThis.requestAnimationFrame = (fn) => window.requestAnimationFrame(fn);
+            globalThis.cancelAnimationFrame = (id) => window.cancelAnimationFrame(id);
+            // queueMicrotask must share the engine's promise-job (microtask)
+            // queue so its callbacks are FIFO-ordered with Promise reactions
+            // (the WHATWG single-microtask-queue model). Routing through the
+            // Ruby scheduler instead would drain on a separate pass, reordering
+            // it after all native promise jobs.
+            globalThis.queueMicrotask = (fn) => {
+              if (typeof fn !== "function") throw new TypeError("queueMicrotask requires a function");
+              Promise.resolve().then(() => { fn(); });
+            };
+          JS
+          win
+        end
+
+        # Expose the seeded interface constructors on a secondary window (an
+        # iframe's contentWindow), so cross-window instanceof / defaultView work.
+        # Call after install_window (the constructors must already be seeded).
+        def expose_constructors_on(window_obj)
+          @bridge.expose_constructors_on(window_obj)
+        end
+
+        # Run a script for side effects (no return value). Wrapped in an IIFE so
+        # statements are allowed and the completion value is voided — otherwise a
+        # trailing Promise expression would trip the gem's "unawaited Promise"
+        # guard. Drains microtasks so queued .then work lands before returning.
+        def execute(js)
+          @backend.eval("(function () {\n#{js}\n})();")
+          drain_microtasks
+          nil
+        end
+
+        # Evaluate JS and return its value, with DOM nodes decoded to Dommy
+        # objects (rather than the empty Hash a raw proxy becomes crossing to
+        # Ruby). Accepts either an expression (`document.title`) or a statement
+        # body that uses `return` (`const x = ...; return x;`): the expression
+        # form is tried first and, on a syntax error, retried as an async
+        # function body. Syntax errors are compile-time so the failed first
+        # attempt runs nothing. The result is awaited, so a Promise resolves
+        # before returning.
+        def evaluate(js)
+          @bridge.decode(eval_tagged("await (#{js.strip.sub(/;\s*\z/, "")})"))
+        rescue ::Quickjs::SyntaxError
+          @bridge.decode(eval_tagged("await (async () => {\n#{js}\n})()"))
+        end
+
+        def drain_microtasks
+          @backend.drain_microtasks
+        end
+
+        # Handle-oriented JS access for a wasm guest (see WasmBridge). Memoized
+        # so the guest's `__rbWasmInvoke` dispatcher (installed via #on_invoke)
+        # stays registered for the VM's lifetime.
+        def wasm_bridge
+          @wasm_bridge ||= WasmBridge.new(@backend)
+        end
+
+        # Drive the event loop to quiescence: drain the native microtask queue,
+        # then advance the deterministic scheduler to its next due timer and drain
+        # again, repeating until no timer is pending. This is the single
+        # deterministic "settle everything" entry point a host uses after an eval
+        # (mirroring a `drain_async!`): every queued microtask runs and every
+        # scheduled timer fires, in WHATWG order (microtasks before each timer).
+        # `max_iterations` bounds runaway timer loops (e.g. a self-rescheduling
+        # setInterval).
+        def run_until_idle(max_iterations: 1000)
+          sched = @window&.scheduler
+          max_iterations.times do
+            drain_microtasks
+            break unless sched
+
+            next_at = sched.next_due_timer_at
+            break unless next_at
+
+            sched.advance_time(next_at - sched.now_ms)
+            drain_microtasks
+          end
+          self
+        end
+
+        # Surface otherwise-swallowed JS promise rejections (see Backend).
+        def on_unhandled_rejection(&block)
+          @backend.on_unhandled_rejection(&block)
+          self
+        end
+
+        # Observe console.* output (see Backend).
+        def on_log(&block)
+          @backend.on_log(&block)
+          self
+        end
+
+        # Wire the bare browser globals frameworks reach for, aliased onto the
+        # installed window: self / location / history / navigator / storages /
+        # CSS / fetch / addEventListener / .... Call after install_window. This
+        # is what lets real frontend bundles (Turbo, …) run unmodified.
+        def install_browser_globals
+          @backend.eval(<<~JS)
+            globalThis.self = globalThis;
+            // Top-level window: parent/top are the window itself (spec), so
+            // frame-walking loops terminate instead of dereferencing undefined.
+            globalThis.parent = globalThis;
+            globalThis.top = globalThis;
+            globalThis.location = window.location;
+            globalThis.history = window.history;
+            globalThis.navigator = window.navigator;
+            globalThis.sessionStorage = window.sessionStorage;
+            globalThis.localStorage = window.localStorage;
+            globalThis.CSS = window.CSS;
+            globalThis.fetch = (...args) => window.fetch(...args);
+            globalThis.addEventListener = (...args) => window.addEventListener(...args);
+            globalThis.removeEventListener = (...args) => window.removeEventListener(...args);
+            globalThis.dispatchEvent = (event) => window.dispatchEvent(event);
+            // The window IS the global object, so JS built-in constructors and
+            // namespaces are also `window` properties (`window.String`,
+            // `window.Number`, …). Mirror them as own props on the window proxy
+            // so code that reads constructors off `window` (e.g. the WPT
+            // reflection harness's `window[type]` casts) resolves them.
+            for (const __n of [
+              "String", "Boolean", "Number", "BigInt", "Symbol", "Object", "Array",
+              "Function", "Date", "RegExp", "Promise", "Map", "Set", "WeakMap",
+              "WeakSet", "Math", "JSON", "Reflect", "Proxy", "Error", "TypeError",
+              "RangeError", "SyntaxError", "Infinity", "NaN", "undefined",
+              "parseInt", "parseFloat", "isNaN", "isFinite", "globalThis",
+            ]) {
+              try { window[__n] = globalThis[__n]; } catch (__e) {}
+            }
+            // Minimal WebAssembly.Memory: the engine provides a real
+            // SharedArrayBuffer but no WebAssembly, and WPT's `common/sab.js`
+            // derives the SAB constructor from
+            // `new WebAssembly.Memory({shared:true}).buffer.constructor`. A
+            // Memory whose `.buffer` is a SharedArrayBuffer is enough to let
+            // those tests (encodeInto, TextDecoder copy, …) exercise shared
+            // buffers with the real codec logic.
+            if (typeof globalThis.WebAssembly === "undefined" && typeof globalThis.SharedArrayBuffer === "function") {
+              globalThis.WebAssembly = {
+                Memory: function (opts) {
+                  const bytes = ((opts && opts.initial) || 0) * 65536;
+                  this.buffer = (opts && opts.shared)
+                    ? new SharedArrayBuffer(bytes)
+                    : new ArrayBuffer(bytes);
+                },
+              };
+            }
+          JS
+          self
+        end
+
+        # Run JS GC then drain, so FinalizationRegistry cleanup callbacks fire and
+        # release handles for proxies that are no longer referenced.
+        def collect_garbage
+          @backend.run_gc
+          @backend.drain_microtasks
+        end
+
+        # Live handle count (introspection for lifetime tests).
+        def registered_count
+          @bridge.registered_count
+        end
+
+        def dispose
+          @backend.dispose
+        end
+
+        private
+
+        def eval_tagged(inner_expr)
+          @backend.eval_awaited("__rbHost.tag(#{inner_expr});")
+        end
+      end
+    end
+  end
+end

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

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

data/lib/dommy/js/quickjs/wasm_bridge.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Dommy
+  module Js
+    module Quickjs
+      # Handle-oriented JS access for a wasm guest (e.g. mruby-in-wasm under
+      # wasmtime-rb). Distinct from the Proxy-based HostBridge: instead of
+      # exposing Ruby DOM objects to JS as proxies, this lets a guest treat any
+      # JS value as an opaque integer ref it can get/set/call/new on — the shape
+      # the guest's `js_*` bridge imports need.
+      #
+      # The JS half lives in host_runtime.js (the `wasm*` functions on
+      # `__rbHost`); this is the thin Ruby facade over them. Every non-primitive
+      # JS value crosses as a `JSValue` (an opaque ref into the VM); primitives
+      # cross as plain Ruby values. Callbacks the guest registers become JS
+      # functions (also refs) that route back through `__rbWasmInvoke`.
+      class WasmBridge
+        # An opaque handle to a JS value living in the VM. `ref` is the integer
+        # id into the JS-side jsRefs table.
+        JSValue = Struct.new(:ref) do
+          def to_s
+            "#<JSValue ref=#{ref}>"
+          end
+        end
+
+        def initialize(backend)
+          @backend = backend
+        end
+
+        # Install the dispatcher JS callbacks route back through. The block
+        # receives (invoke_id, packed_args) and must return a packed result
+        # (the same tagged shape #pack produces). Called once by the embedder.
+        def on_invoke(&block)
+          @backend.define_host_function("__rbWasmInvoke") do |invoke_id, args|
+            block.call(invoke_id.to_i, args)
+          end
+          self
+        end
+
+        # A ref to the VM's globalThis — the guest's `js_global`.
+        def global_ref
+          unpack(@backend.call_js("__rbHost.wasmGlobalRef"))
+        end
+
+        # Evaluate real JS source in global scope; returns the (packed) result.
+        def eval_js(src)
+          unpack(@backend.call_js("__rbHost.wasmEval", src.to_s))
+        end
+
+        def get(recv, prop)
+          unpack(@backend.call_js("__rbHost.wasmGet", ref_of(recv), prop.to_s))
+        end
+
+        def set(recv, prop, value)
+          @backend.call_js("__rbHost.wasmSet", ref_of(recv), prop.to_s, pack(value))
+          nil
+        end
+
+        def call(recv, method, args)
+          unpack(@backend.call_js("__rbHost.wasmCall", ref_of(recv), method.to_s, args.map { |a| pack(a) }))
+        end
+
+        # Apply a function ref directly (optionally with an explicit `this`).
+        def apply(fn, this_arg, args)
+          this_ref = this_arg.nil? ? nil : ref_of(this_arg)
+          unpack(@backend.call_js("__rbHost.wasmApply", ref_of(fn), this_ref, args.map { |a| pack(a) }))
+        end
+
+        def construct(ctor, args)
+          unpack(@backend.call_js("__rbHost.wasmNew", ref_of(ctor), args.map { |a| pack(a) }))
+        end
+
+        def typeof(value)
+          @backend.call_js("__rbHost.wasmTypeof", ref_of(value))
+        end
+
+        def to_string(value)
+          @backend.call_js("__rbHost.wasmToString", ref_of(value))
+        end
+
+        def strict_equal(a, b)
+          @backend.call_js("__rbHost.wasmStrictEqual", ref_of(a), ref_of(b))
+        end
+
+        def js_null?(value)
+          return value.nil? unless value.is_a?(JSValue)
+
+          @backend.call_js("__rbHost.wasmIsNull", value.ref)
+        end
+
+        def instance_of?(value, ctor)
+          @backend.call_js("__rbHost.wasmInstanceof", ref_of(value), ref_of(ctor))
+        end
+
+        # Make a JS function (returned as a ref) that calls back into the guest
+        # with the given invoke-id when invoked.
+        def make_callback(invoke_id)
+          unpack(@backend.call_js("__rbHost.wasmMakeCallback", invoke_id.to_i))
+        end
+
+        def release(value)
+          @backend.call_js("__rbHost.wasmReleaseRef", value.ref) if value.is_a?(JSValue)
+          nil
+        end
+
+        # Ruby value -> wasm-tagged JS value. Public so the embedder's
+        # #on_invoke dispatcher can pack the values it hands back into JS.
+        def pack(value)
+          case value
+          when JSValue then {"__rb_js_ref" => value.ref}
+          when nil, true, false, Integer, Float, String then value
+          when Symbol then value.to_s
+          when Array then value.map { |e| pack(e) }
+          when Hash then value.each_with_object({}) { |(k, v), h| h[k.to_s] = pack(v) }
+          else
+            raise ArgumentError, "cannot pack #{value.class} for the wasm JS bridge"
+          end
+        end
+
+        # wasm-tagged JS value -> Ruby value (JSValue for refs). Public for the
+        # same reason as #pack.
+        def unpack(value)
+          case value
+          when Hash
+            if value.key?("__rb_js_ref")
+              JSValue.new(value["__rb_js_ref"])
+            elsif value.key?("__rb_undefined")
+              nil
+            elsif value.key?("__rb_bytes")
+              value["__rb_bytes"]
+            elsif value.key?("__rb_arraybuffer")
+              value["__rb_arraybuffer"]
+            else
+              value.each_with_object({}) { |(k, v), h| h[k] = unpack(v) }
+            end
+          when Array then value.map { |e| unpack(e) }
+          else value
+          end
+        end
+
+        private
+
+        def ref_of(value)
+          return value.ref if value.is_a?(JSValue)
+
+          raise ArgumentError, "expected a JSValue receiver, got #{value.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/dommy/js/quickjs.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "quickjs/version"
+
+module Dommy
+  module Js
+    module Quickjs
+      class Error < StandardError; end
+    end
+  end
+end
+
+require_relative "handle_table"
+require_relative "dom_interfaces"
+require_relative "constructor_registry"
+require_relative "custom_elements"
+require_relative "host_bridge"
+require_relative "quickjs/backend"
+require_relative "quickjs/wasm_bridge"
+require_relative "quickjs/runtime"

data/sig/dommy/js/quickjs.rbs

@@ -0,0 +1,8 @@
+module Dommy
+  module Js
+    module Quickjs
+      VERSION: String
+      # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    end
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: dommy-js-quickjs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- takahashim
+bindir: exe
+cert_chain: []
+date: 2026-05-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: quickjs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.18.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.18.0
+- !ruby/object:Gem::Dependency
+  name: dommy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+description: |
+  dommy-js-quickjs lets JavaScript drive a Dommy DOM by embedding QuickJS (via
+  the quickjs gem) and bridging DOM nodes to JS through an ES Proxy that routes
+  property/method access into Dommy's __js_get__ / __js_set__ / __js_call__ ABI.
+email:
+- takahashimm@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/bridge-redesign.md
+- docs/wpt-conformance.md
+- lib/dommy/js/constructor_registry.rb
+- lib/dommy/js/custom_elements.rb
+- lib/dommy/js/dom_interfaces.rb
+- lib/dommy/js/handle_table.rb
+- lib/dommy/js/host_bridge.rb
+- lib/dommy/js/host_runtime.js
+- lib/dommy/js/observable_runtime.js
+- lib/dommy/js/quickjs.rb
+- lib/dommy/js/quickjs/backend.rb
+- lib/dommy/js/quickjs/capybara.rb
+- lib/dommy/js/quickjs/runtime.rb
+- lib/dommy/js/quickjs/version.rb
+- lib/dommy/js/quickjs/wasm_bridge.rb
+- sig/dommy/js/quickjs.rbs
+homepage: https://github.com/takahashim/dommy-js-quickjs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/takahashim/dommy-js-quickjs
+  source_code_uri: https://github.com/takahashim/dommy-js-quickjs
+  bug_tracker_uri: https://github.com/takahashim/dommy-js-quickjs/issues
+  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: 3.6.2
+specification_version: 4
+summary: QuickJS backend for running JavaScript against a Dommy DOM.
+test_files: []