dommy-js-quickjs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 17fc429b996f9fb344e581d754fa51c5a0e27d559caca8709fdd1dd6bcbd8516
+  data.tar.gz: de228d74c5b14116c3eae917154823c00f0cd3c5f3c81a89d4b33d1c89c6b44b
+SHA512:
+  metadata.gz: a4340bfcd9e6c084ee9441bafc176752bb97601814d460fd39cac699553faf52c972d08f844011a957c90b0df7b4c83b609df618f10d9545a58e4d22bb314f0e
+  data.tar.gz: 628bb3957b81036927500ee813d6b0410bc936ac378e35efc27990f8cc59c6d5ed4eb9b18bd9e1baed781bb813a7d09d864c1bf74e40d50b03cac588e0d5ec3a

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+initial release.
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Masayoshi Takahashi
+
+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,150 @@
+# Dommy::Js::Quickjs
+
+Run real JavaScript — including real frontend frameworks — against a
+[Dommy](https://github.com/takahashim/dommy) DOM, without a browser.
+
+JavaScript executes in an embedded QuickJS VM (via the
+[`quickjs`](https://github.com/hmsk/quickjs.rb) gem). Dommy DOM nodes are bridged
+to JS as objects whose property/method access routes into Dommy's
+`__js_get__` / `__js_set__` / `__js_call__` / `__js_new__` ABI, so JS drives a
+real Dommy document. The QuickJS-specific code is isolated in a small `Backend`;
+the rest of the bridge is engine-agnostic.
+
+The bridge presents a **spec-shaped JS DOM**, not bare proxies: `instanceof`,
+prototype chains, `Object.prototype.toString` brands, constructable interfaces
+(`new Event(...)`), custom elements (`class extends HTMLElement`), live
+collections, and expandos all work — enough that the real
+[`@hotwired/turbo`](https://github.com/hotwired/turbo) bundle loads and drives
+the DOM (turbo-stream + turbo-frame; see `test/dommy/js/test_turbo_integration.rb`).
+
+## Installation
+
+In your `Gemfile`:
+
+```ruby
+gem "dommy-js-quickjs"
+```
+
+## Usage
+
+```ruby
+require "dommy"
+require "dommy/js/quickjs"
+
+win = Dommy.parse("<h1 class='title'>Hi</h1>")
+
+rt = Dommy::Js::Quickjs::Runtime.new
+rt.define_host_object("document", win.document)
+rt.install_window(win) # exposes `window` + bare timer globals (setTimeout, ...)
+
+rt.evaluate('document.querySelector(".title").textContent')        # => "Hi"
+rt.execute('document.querySelector(".title").textContent = "Bye"') # mutates the DOM
+win.document.query_selector(".title").text_content                 # => "Bye"
+```
+
+- `evaluate(js)` — evaluate an expression (or a `return`-using statement body) and
+  return the value; DOM nodes come back as Dommy objects, Promises are awaited.
+- `execute(js)` — run statements for side effects; drains microtasks.
+- Timers ride Dommy's scheduler: `win.scheduler.advance_time(ms)` fires JS
+  `setTimeout` / `setInterval` / `requestAnimationFrame` callbacks.
+- `run_until_idle` — drive the event loop to quiescence: drains microtasks, then
+  advances the scheduler to each due timer and drains again, in WHATWG order
+  (microtasks before each timer), until nothing is pending. The one-call
+  "settle everything" entry point after an eval (`max_iterations:` bounds
+  self-rescheduling timer loops).
+
+## What the JS sees
+
+The JS-facing DOM behaves like a browser's, not like a plain object graph:
+
+```js
+const el = document.querySelector("button");
+el instanceof HTMLElement                       // true (full prototype chain)
+Object.prototype.toString.call(el)              // "[object HTMLButtonElement]"
+el.constructor.name                             // "HTMLButtonElement"
+
+new CustomEvent("x", { detail: 1 })             // constructable interfaces
+el.dispatchEvent(new CustomEvent("x", {...}))   // events bubble; detail round-trips
+
+for (const c of el.children) { /* ... */ }      // live, iterable collections
+el.querySelectorAll("li").map(n => n.tagName)   // NodeList crosses as a JS array
+
+el._state = { n: 1 }; el._state === el._state   // expandos keep their identity
+
+class Card extends HTMLElement {                 // custom elements
+  connectedCallback() { this.textContent = "hi"; }
+}
+customElements.define("x-card", Card);
+```
+
+Method-vs-property is taken from each Dommy class's `__js_method_names__`, so no
+method list is maintained here.
+
+## Running real frameworks (and testing components)
+
+To run a real bundle you need the browser globals it reaches for and a way to
+drive deferred work. `BrowserHarness` (under `test/support/`) packages this:
+
+```ruby
+h = Dommy::Js::BrowserHarness.new(
+  "<body><div id='app'></div></body>",
+  fetch_stub: { "http://localhost/frame" => { status: 200, contentType: "text/html", body: "..." } }
+)
+h.load_script("vendor/turbo.umd.js")   # runs the real bundle
+h.execute("/* your app / interactions */")
+h.pump                                  # drive microtasks + the scheduler clock
+assert_empty h.errors                   # nothing was silently swallowed
+```
+
+The pieces it relies on are public Runtime API:
+
+- `Runtime#install_browser_globals` — wire the bare globals real bundles use
+  (`self` / `location` / `history` / `navigator` / storages / `CSS` / `fetch` /
+  `addEventListener` / …), aliased onto the installed window.
+- `Runtime#on_unhandled_rejection { |err| }` — surface promise rejections that
+  reach the microtask queue with no handler. Frameworks swallow these; `err.backtrace`
+  carries the JS stack, which is the difference between blind and one-shot debugging.
+- `Runtime#on_log { |log| }` — observe `console.*` (`log.severity` / `log.to_s`).
+
+### Capybara
+
+Requiring the adapter enables `execute_script` / `evaluate_script` on
+`Capybara::Dommy::Driver` (capybara-dommy stays JS-free without it):
+
+```ruby
+require "dommy/js/quickjs/capybara"
+```
+
+## Limitations
+
+- **Deterministic scheduler, no wall clock.** Async work (timers, `requestAnimationFrame`,
+  framework "next repaint" deferral) only advances via `win.scheduler.advance_time(ms)` —
+  drive it with `Runtime#run_until_idle`, `BrowserHarness#pump`, or manually.
+  Selenium-style `done()` / real-time waits are not supported.
+- **`fetch` is stub-based** via Dommy's `__fetchy_stub__` (a `{ url => entry }` map);
+  there is no real network.
+- **Event listeners must be functions** — `addEventListener("...", fn)` works
+  (closures intact; `removeEventListener` with the same function detaches it), but
+  the `{ handleEvent }` object form is not.
+- **Expandos are scoped to elements**, and the JS callback table is not evicted, so
+  a very long-lived VM can grow unbounded.
+- **DOM coverage is Dommy's.** A JS method/property works only where Dommy exposes
+  it via the ABI (`__js_method_names__` / `__js_get__`); gaps surface as
+  `undefined` / "not a function" (see `on_unhandled_rejection`).
+
+## Development
+
+Run `bin/setup` to install dependencies, then `rake test`. `bin/console` opens an
+interactive prompt.
+
+The real-framework integration test (`test_turbo_integration.rb`) is skipped
+unless the Turbo bundle is vendored at `test/fixtures/turbo.umd.js`:
+
+```bash
+curl -sL https://unpkg.com/@hotwired/turbo@8/dist/turbo.es2017-umd.js \
+  -o test/fixtures/turbo.umd.js
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/takahashim/dommy-js-quickjs.

data/Rakefile

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test
+
+namespace :wpt do
+  desc "Run the vendored WPT corpus against the bridge and report a conformance rate"
+  task :conformance, [:filter] do |_t, args|
+    $LOAD_PATH.unshift File.expand_path("test", __dir__)
+    require "test_helper"
+    require "support/wpt_runner"
+
+    runner = Dommy::Js::WptRunner
+    files = runner.manifest
+    files = files.grep(/#{args[:filter]}/) if args[:filter]
+
+    total_pass = total = file_ok = 0
+    blocked = []
+    by_dir = Hash.new { |h, k| h[k] = [0, 0] } # dir => [pass, total]
+    files.each do |rel|
+      results = runner.run(rel)
+      pass = results.count(&:pass?)
+      n = results.size
+      total_pass += pass
+      total += n
+      dir = rel.split("/").first
+      by_dir[dir][0] += pass
+      by_dir[dir][1] += n
+      file_ok += 1 if n.positive? && pass == n
+      flag = n.zero? ? "—" : (pass == n ? "✓" : " ")
+      printf("  %s %-46s %3d/%-3d\n", flag, rel, pass, n)
+      results.reject(&:pass?).first(3).each { |r| puts "        #{r.to_s[0, 110]}" }
+    rescue => e
+      blocked << rel
+      puts "  ✗ #{rel}  (errored: #{e.class}: #{e.message[0, 80]})"
+    end
+
+    pct = ->(p, t) { t.zero? ? 0 : (100.0 * p / t).round(1) }
+    puts
+    by_dir.sort.each { |dir, (p, t)| printf("  %-8s %4d/%-5d (%.1f%%)\n", dir, p, t, pct.call(p, t)) }
+    puts
+    puts "WPT conformance: #{total_pass}/#{total} subtests (#{pct.call(total_pass, total)}%) across #{files.size} files; " \
+         "#{file_ok} files fully green#{blocked.empty? ? "" : ", #{blocked.size} errored"}"
+  end
+end