dommy-js-quickjs 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56e600a474810ea778587cf249cbb7c200d9947c28270449837550971e5674de
-  data.tar.gz: ff9e6cf37ed37fb89f148163e38ee6fdd63e8bd5fc1e81669f8538eebc84d3ea
+  metadata.gz: df093cff1000de6ad73f27367c17845c2b6846b87785913d70695b0d38938daf
+  data.tar.gz: aab8821f4e6974306d7e47b35730f32d7340cec51437d0926e94986e692bbb4d
 SHA512:
-  metadata.gz: ffa632c98fe6c8bedba9bc8e189cda13a1c9baef1c4bd0224fa1f7f9ffd31bdcaad8bcb84ffdbdf2b2436ec3a29bb68d0d8ceaa7879602f5cc45d8edbc1633ba
-  data.tar.gz: 22272e499d364204ecba6edb91cb6c01953d72d46990652b3f14907e2141686e8bbc8d94de3d5125e2f96b21e9e1a34b8d5c887c41af3dbe8cd693e33a2370bd
+  metadata.gz: efe4b423fc15fc33f2e3a77108f145cadf0d4d072b69c9447f958cbdcb872b367cd7857ce07a975bacb2d7a64a36c3bee760a4070ebfcc893bff8e6df8ea8441
+  data.tar.gz: c5fa56f132d9df6e4c067f96f0fa5c1e915c63d9ff641832c72aac75307e6fad57d7e671e4585e0cdffe73419cba0e965a08d750e2c50e5dfbad223b5987c6f1

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.11.0 — 2026-10-04
+
+Requires `dommy >= 0.15.0, < 0.16` and `quickjs ~> 0.22.0`.
+
+### Added
+
+- ES modules can be preloaded as bytecode. `Runtime.register_module(name, source:)` registers a module once per process (wrapping `Quickjs.register_module`), and `Runtime.new(preload_modules: [name, …])` reads registered modules into the new VM, so a later page loads them without parsing their source again. A preloaded module is found before the module loader is asked for its name, and a loader that returns `{as: name}` for another specifier lands on it too. dommy's `Dommy::Js::ModulePreload` drives both: with it enabled, a page that imports Turbo as an ES module boots in about 11 ms instead of 24 ms from the third page on.
+
+### Changed
+
+- Requires `dommy >= 0.15.0, < 0.16` (was `>= 0.14.0, < 0.15`), the release whose `ModulePreload` uses the API above and whose behavior the suite checks.
+- Requires `quickjs ~> 0.22.0` (was `~> 0.21.0`). 0.22.0 releases [hmsk/quickjs.rb#141](https://github.com/hmsk/quickjs.rb/pull/141): an unhandled rejection is reported at the end of the microtask checkpoint, as HTML requires, so `Promise.reject(x).catch(...)` and `try { await rejecting() } catch {}` are no longer misreported. On a RubyGems install, `on_unhandled_rejection` reports again, a strict `Dommy::Browser` fails on a rejection the page leaves unhandled, and the page's `unhandledrejection` event fires. `event.reason` and `event.promise` are still not the page's own values there, and `rejectionhandled` does not fire: those need the JS rejection hook, which no quickjs release has yet.
+- The development Gemfile pins the quickjs fork that carries the hook by tag ([`v0.22.0-rejection-hook.1`](https://github.com/takahashim/quickjs.rb/tree/v0.22.0-rejection-hook.1)) rather than by commit, so the fork's branch can be rebased onto each upstream release without stranding the ref an older commit pins.
+- The suite no longer takes `DOMMY_BACKEND`: dommy 0.15 has Makiri as its only backend.
+
+### Removed
+
+- The 0.21.0 workaround is gone: `Backend.premature_rejection_reports?`, its once-per-process probe, and the warning `on_unhandled_rejection` gave in place of reporting. No quickjs the gemspec allows behaves that way.
+
 ## 0.10.0 — 2026-10-01
 
 Requires `dommy >= 0.14.0, < 0.15` and `quickjs ~> 0.21.0`.

data/README.md

@@ -110,15 +110,37 @@ The pieces it relies on are public Runtime API:
 - `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.
-  The released quickjs (0.21.0) reports a rejection before a handler attached in
-  the same microtask checkpoint can catch it, so `.catch` and `try { await … }
-  catch` would look unhandled; on such an engine nothing is reported here (a
-  warning says so once), so a strict `Dommy::Browser` does not fail on
-  rejections and the page's `unhandledrejection` event (and
-  `window.onunhandledrejection`) never fires. A quickjs with
-  [hmsk/quickjs.rb#141](https://github.com/hmsk/quickjs.rb/pull/141) reports them.
 - `Runtime#on_log { |log| }` — observe `console.*` (`log.severity` / `log.to_s`).
 
+### Preloading ES modules
+
+A module the loader hands over as source is parsed again by every Runtime that
+imports it. Register it once per process and later Runtimes read it in as
+bytecode instead:
+
+```ruby
+Dommy::Js::Quickjs::Runtime.register_module("https://example.test/vendor/turbo.js", source: turbo_js)
+
+rt = Dommy::Js::Quickjs::Runtime.new(preload_modules: ["https://example.test/vendor/turbo.js"])
+rt.module_loader = ->(specifier, _importer) {
+  {as: "https://example.test/vendor/turbo.js"} if specifier == "@hotwired/turbo"
+}
+```
+
+- The name is the module's canonical name: the VM keys its module map by it,
+  and the module's relative imports resolve against it. Register a page's
+  module under its resolved URL.
+- `source:` may be a Proc returning the source; it is read when a Runtime first
+  preloads the module, and the bytecode is shared from then on. Each Runtime
+  still gets its own instance, with its own module-level state.
+- A preloaded module is found before the loader is asked for its name. A loader
+  that returns `{as: name}` for another specifier (an importmap entry, say)
+  lands on it too.
+- A preloaded module's own imports are not preloaded; register each one you
+  want cached. Naming a module that is not registered raises `ArgumentError`.
+- Preloading bypasses the loader for that name, so do not preload a module the
+  loader would refuse to some importers.
+
 ### Capybara
 
 Requiring the adapter enables `execute_script` / `evaluate_script` on

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

@@ -45,42 +45,9 @@ module Dommy
       # the top-level tag); either way it maps to Dommy::Bridge::UNDEFINED. No
       # normalization is needed here.
       class Backend
-        # Whether this quickjs reports a promise rejection the moment it
-        # happens, before a handler attached later in the same microtask
-        # checkpoint gets the chance — the released quickjs (0.21.0) does, so
-        # `Promise.reject(x).catch(f)` and `try { await p } catch {}` both
-        # come out as unhandled. HTML reports at the end of the checkpoint
-        # (hmsk/quickjs.rb#141, merged upstream but unreleased).
-        #
-        # Decided by behavior, not by version — a git checkout of the fixed
-        # engine still says 0.21.0 — on a throwaway VM, once per process.
-        def self.premature_rejection_reports?
-          return @premature_rejection_reports if defined?(@premature_rejection_reports)
-
-          @premature_rejection_reports = probe_premature_rejection_reports
-        end
-
-        def self.probe_premature_rejection_reports
-          vm = ::Quickjs::VM.new
-          reported = false
-          vm.on_unhandled_rejection { |_error| reported = true }
-          vm.eval_code(<<~JS, async: false)
-            Promise.reject(1).catch(function () {});
-            (async function () { try { await Promise.reject(2); } catch (e) {} })();
-            0
-          JS
-          vm.drain_jobs!
-          reported
-        rescue ::StandardError
-          # A probe that cannot run says nothing either way; keep reporting.
-          false
-        ensure
-          vm&.dispose!
-        end
-        private_class_method :probe_premature_rejection_reports
-
         # Timeout and memory ceiling both differ from the gem's defaults, for
-        # reasons Config documents.
+        # reasons Config documents. Every other option goes to the VM as is,
+        # `preload_modules:` among them (see Runtime#initialize).
         def initialize(**vm_opts)
           vm_opts = {timeout_msec: Config.timeout_msec, memory_limit: Config.memory_limit}.merge(vm_opts)
           @vm = ::Quickjs::VM.new(**vm_opts)
@@ -114,6 +81,14 @@ module Dommy
           ::Quickjs.compile(source, filename: filename)
         end
 
+        # Register an ES module process-wide under its canonical name: compiled
+        # to bytecode once, on the first VM that preloads it, and read into each
+        # VM that names it in `preload_modules:`. `source:` is a String or a Proc
+        # returning one.
+        def self.register_module(name, source:)
+          ::Quickjs.register_module(name, source: source)
+        end
+
         # Process-global cache for the engine-internal runtime bundles run via
         # #run_bundle (host_runtime.js, observable_runtime.js). Kept separate
         # from ScriptCache (user-facing external scripts) so the two concerns
@@ -143,8 +118,8 @@ module Dommy
         def eval_awaited(js) = guarded { @vm.eval_code(js, async: true) }
 
         # Install the ESM module resolver: a callable `(specifier, importer) ->
-        # source String | { code:, as: } | nil` the engine consults for every
-        # static/dynamic `import`. nil clears it (engine default loader).
+        # source String | { code:, as: } | { as: } | nil` the engine consults for
+        # every static/dynamic `import`. nil clears it (engine default loader).
         def module_loader=(callable)
           @vm.module_loader = callable
         end

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

@@ -21,8 +21,23 @@ module Dommy
       # What stays here is the port itself: script evaluation, and the wiring
       # that decides which collaborator answers a host's call.
       class Runtime
-        def initialize(**vm_opts)
-          @backend = Backend.new(**vm_opts)
+        # Register an ES module process-wide, so a later Runtime can preload it
+        # as bytecode instead of parsing its source again. `name` is the
+        # module's canonical name — the one the VM's module map keys it by and
+        # its relative imports resolve against — so a page module is best
+        # registered under its resolved URL. `source:` is a String or a Proc
+        # returning one (read only when a Runtime first preloads it).
+        def self.register_module(name, source:)
+          Backend.register_module(name, source: source)
+        end
+
+        # `preload_modules:` names registered modules (see .register_module) to
+        # read into this Runtime's VM as it is made. A preloaded module is found
+        # before the module loader is asked for its name, and a loader that
+        # returns `{as: name}` for another specifier lands on it too. A name not
+        # registered raises ArgumentError. Other options go to the VM.
+        def initialize(preload_modules: [], **vm_opts)
+          @backend = Backend.new(preload_modules: preload_modules, **vm_opts)
           @bridge = Dommy::Js::HostBridge.new(@backend)
           @environment = BrowserEnvironment.new(@backend)
           @errors = ErrorTranslator.new(@backend, @bridge)
@@ -113,7 +128,9 @@ module Dommy
         end
 
         # Install the ESM module resolver (see Backend#module_loader=). A
-        # callable `(specifier, importer) -> source | {code:, as:} | nil`.
+        # callable `(specifier, importer) -> source | {code:, as:} | {as:} | nil`;
+        # `{as: name}` with no code redirects to a module the VM already has,
+        # such as one in `preload_modules:`.
         def module_loader=(callable)
           @backend.module_loader = callable
         end
@@ -195,19 +212,11 @@ module Dommy
         # Surface otherwise-swallowed JS promise rejections (see Backend).
         # Goes quiet once the JS hook is installed: both would fire for the same
         # rejection, and the hook carries strictly more.
-        #
-        # Goes quiet, too, on an engine that reports a rejection before a
-        # handler could attach (Backend.premature_rejection_reports?): there
-        # every `.catch` and `try { await … } catch` would surface as an
-        # unhandled rejection and fail a strict host on correct code. Reporting
-        # none is the lesser loss — a rejection the page truly leaves unhandled
-        # goes unreported until the engine is fixed.
         def on_unhandled_rejection(&block)
           # Decided when a rejection actually arrives, not now: a host registers
           # this before #install_window, which is where the hook goes in.
           relay = lambda do |error|
             next if js_rejection_hook?
-            next self.class.warn_premature_rejection_reports if Backend.premature_rejection_reports?
 
             block.call(@track_rejections ? @errors.enrich_rejection(error) : error)
           end
@@ -215,17 +224,6 @@ module Dommy
           self
         end
 
-        # Said once per process, on the first rejection left unreported.
-        def self.warn_premature_rejection_reports
-          return if @warned_premature_rejection_reports
-
-          @warned_premature_rejection_reports = true
-          warn "dommy-js-quickjs: this quickjs (#{::Quickjs::VERSION}) reports a promise rejection before " \
-               "a handler can attach, so unhandled rejections are not reported. A quickjs with " \
-               "hmsk/quickjs.rb#141 (unhandled-rejection timing) reports them."
-          nil
-        end
-
         # Whether rejections arrive through the JS hook. A host that also relays
         # #on_unhandled_rejection would otherwise report each rejection twice.
         def js_rejection_hook? = !!@js_rejection_hook

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

@@ -3,7 +3,7 @@
 module Dommy
   module Js
     module Quickjs
-      VERSION = "0.10.0"
+      VERSION = "0.11.0"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dommy-js-quickjs
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - takahashim
@@ -15,34 +15,34 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: 0.22.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.21.0
+        version: 0.22.0
 - !ruby/object:Gem::Dependency
   name: dommy
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: 0.15.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.16'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.14.0
+        version: 0.15.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.15'
+        version: '0.16'
 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