moxml 0.1.24 → 0.1.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c61c5dcecbe10b9f0f2850a134c9a8c5e2ec7d0be5b5b1dbb828dac25019a55
-  data.tar.gz: f418e1f7a7406bfcc0dd9e57bc2a6b372a332b0e6677821a9e2b7a8173871b45
+  metadata.gz: ed30996109d8cfb8057f216677cba8ca3cd3856287c38b6a7edab3251ebb2064
+  data.tar.gz: f93d7c13863ef9d437e40403e4a48434ed1e1c5530ea2424cdeff710740243a0
 SHA512:
-  metadata.gz: 44ccdeb45ec15bdadb02a470bd8506f051ee22385a0832b78d17b607ef32a192b28f0ec716f7910f2ba22c106b0a48ffec85aaaf1dbe33f7ce4a1f4fd7108695
-  data.tar.gz: 49ed1641cd66fe4efa02f0e072b07621f441e3936734aba4ebb58a2f9188fab5feae920c989b21476019b01fac1562afc36356059d4c979f9a41b8f3e29686ec
+  metadata.gz: 9b09c144a268507bb02a16a4c6ba7caf6d1a2fa003718a6fa0960a8b68ba03a09584a66fb9475b1c23cd2d79071f1cc8c313200749f997d317aa90e61fba3811
+  data.tar.gz: 6389858a232d82faad5f6bbfd22d4828801c7a6d45a55a2a0f08d28c44647a588b52d2106649d408777453b571815b40c191f48c374cc49b648c58ad2be1e835

data/.github/workflows/docs.yml

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1

data/.github/workflows/opal.yml

@@ -21,16 +21,33 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: "3.4"
-          bundler-cache: true
+          # NOTE: bundler-cache is disabled because the path-source oga
+          # and ruby-ll forks need ragel + ruby-ll outputs generated
+          # (rake vendor:prepare) before their C extensions can compile.
+          bundler-cache: false
 
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
           node-version: "18"
 
+      - name: Install ragel
+        run: sudo apt-get update && sudo apt-get install -y ragel
+
+      - name: Install ruby-ll (for rake vendor:prepare)
+        run: gem install ruby-ll --no-document
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        # Run before `bundle install`: the path-source oga/ruby-ll forks
+        # gitignore their generated .rb/.c files (parser.rb, lexer.rb,
+        # ext/c/lexer.c). bundle install compiles the C extensions via
+        # each fork's extconf.rb, which requires ext/c/lexer.c to exist.
+        run: rake vendor:prepare
+
       - name: Install Opal dependencies
         run: |
           npm list -g opal-compiler || npm install -g opal-compiler
+          bundle install
           bundle exec rake opal:generate_entity_data
 
       - name: Run Opal tests

data/.github/workflows/rake.yml

@@ -13,14 +13,43 @@ jobs:
   rake:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@v6
+        with:
+          submodules: "recursive"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
         with:
           ruby-version: "3.3"
-          bundler-cache: true
+          # bundler-cache is disabled because the path-source oga
+          # and ruby-ll forks need ragel + ruby-ll outputs generated
+          # (rake vendor:prepare) before their C extensions can compile.
+          bundler-cache: false
+
+      - name: Install ragel
+        run: sudo apt-get update && sudo apt-get install -y ragel
+
+      - name: Install ruby-ll (for rake vendor:prepare)
+        run: gem install ruby-ll --no-document
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        # Run before `bundle install`: the path-source oga/ruby-ll forks
+        # gitignore their generated .rb/.c files (parser.rb, lexer.rb,
+        # ext/c/lexer.c). bundle install compiles the C extensions via
+        # each fork's extconf.rb, which requires ext/c/lexer.c to exist.
+        run: rake vendor:prepare
+
       - name: Install dependencies
         run: bundle install
+
+      - name: Compile liboga / libll native extensions
+        # Bundler does not reliably build path-source gems' native
+        # extensions; compile them explicitly so `require "oga"` (which
+        # requires libll) resolves under CRuby.
+        run: rake vendor:compile
+
       - name: Run fast tests (unit + adapter + integration)
         run: bundle exec rake spec:fast
+
       - name: Run rubocop
         run: bundle exec rubocop

data/.github/workflows/round-trip.yml

@@ -19,11 +19,34 @@ jobs:
         ruby: [ "3.1", "3.2", "3.3", "3.4", "4.0" ]
         category: [ metanorma, rfcxml, niso-jats ]
     steps:
-      - uses: actions/checkout@v4
-      - uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@v6
+        with:
+          submodules: "recursive"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
-          bundler-cache: true
+          # bundler-cache is disabled because the path-source oga
+          # and ruby-ll forks need ragel + ruby-ll outputs generated
+          # (rake vendor:prepare) before their C extensions can compile.
+          bundler-cache: false
+
+      - name: Install ragel
+        run: sudo apt-get update && sudo apt-get install -y ragel
+
+      - name: Install ruby-ll (for rake vendor:prepare)
+        run: gem install ruby-ll --no-document
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        run: rake vendor:prepare
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Compile liboga / libll native extensions
+        run: rake vendor:compile
+
       - name: Run round-trip tests (${{ matrix.category }})
         run: bundle exec rspec spec/consistency/ --tag round_trip --tag fixture_category:${{ matrix.category }}
         env:
@@ -39,11 +62,31 @@ jobs:
         ruby: [ "3.3", "4.0" ]
         category: [ metanorma, rfcxml, niso-jats ]
     steps:
-      - uses: actions/checkout@v4
-      - uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@v6
+        with:
+          submodules: "recursive"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
-          bundler-cache: true
+          bundler-cache: false
+
+      - name: Install ragel
+        run: sudo apt-get update && sudo apt-get install -y ragel
+
+      - name: Install ruby-ll (for rake vendor:prepare)
+        run: gem install ruby-ll --no-document
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        run: rake vendor:prepare
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Compile liboga / libll native extensions
+        run: rake vendor:compile
+
       - name: Run Nokogiri × Ox round-trip tests (${{ matrix.category }})
         run: bundle exec rspec spec/consistency/ --tag round_trip --tag fixture_category:${{ matrix.category }}
         env:
@@ -61,11 +104,31 @@ jobs:
         ruby: [ "3.3", "4.0" ]
         category: [ metanorma, rfcxml, niso-jats ]
     steps:
-      - uses: actions/checkout@v4
-      - uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@v6
+        with:
+          submodules: "recursive"
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
-          bundler-cache: true
+          bundler-cache: false
+
+      - name: Install ragel
+        run: sudo apt-get update && sudo apt-get install -y ragel
+
+      - name: Install ruby-ll (for rake vendor:prepare)
+        run: gem install ruby-ll --no-document
+
+      - name: Generate ragel / ruby-ll outputs in vendored forks
+        run: rake vendor:prepare
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Compile liboga / libll native extensions
+        run: rake vendor:compile
+
       - name: Run Nokogiri × REXML round-trip tests (${{ matrix.category }})
         run: bundle exec rspec spec/consistency/ --tag round_trip --tag fixture_category:${{ matrix.category }}
         env:

data/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "opal-oga"]
+	path = vendor/opal-oga
+	url = git@github.com:lutaml/opal-oga.git
+[submodule "opal-ruby-ll"]
+	path = vendor/opal-ruby-ll
+	url = git@github.com:lutaml/opal-ruby-ll.git

data/.rubocop_todo.yml

@@ -675,6 +675,8 @@ RSpec/SpecFilePathFormat:
     - '**/spec/routing/**/*'
     - 'spec/moxml/node_type_map_spec.rb'
     - 'spec/moxml/opal_rexml_adapter_spec.rb'
+    - 'spec/moxml/opal_oga_adapter_spec.rb'
+    - 'spec/moxml/adapter/platform_spec.rb'
     - 'spec/moxml/xpath/ast/node_spec.rb'
     - 'spec/moxml/xpath/cache_spec.rb'
     - 'spec/moxml/xpath/compiler_spec.rb'

data/Gemfile

@@ -11,11 +11,19 @@ gem "benchmark-ips"
 gem "get_process_mem"
 gem "libxml-ruby", "~> 5.0"
 gem "nokogiri", "~> 1.18"
-gem "oga", "~> 3.4"
 gem "openssl", "~> 3.0"
 gem "ox", "~> 2.14"
 gem "rake"
 gem "rexml"
+
+# Opal-compatible forks of oga and ruby-ll. The forks add pure-Ruby lexer
+# and driver fallbacks (under ext/pureruby/) plus an Opal-aware conditional
+# in lib/oga.rb / lib/ll/setup.rb that selects the pure-Ruby implementation
+# when RUBY_PLATFORM == 'opal'. Under CRuby/JRuby the forks behave
+# identically to upstream (the conditional falls through to liboga/libll).
+gem "oga", path: "vendor/opal-oga"
+gem "ruby-ll", path: "vendor/opal-ruby-ll"
+
 gem "rspec"
 gem "rubocop"
 gem "rubocop-performance"

data/README.adoc

@@ -889,6 +889,130 @@ performance optimization, and testing strategies, see
 link:docs/_pages/best-practices.adoc[Best Practices Guide].
 
 
+== Running under Opal (JavaScript)
+
+Opal compiles Ruby to JavaScript and cannot load C extensions. To run
+Moxml on Opal you need three things: an adapter with no native code, a
+XML library fork that exposes pure-Ruby fallbacks for its lexer and
+parser driver, and an Opal build that puts those pure-Ruby
+implementations on the load path.
+
+=== Default adapter under Opal
+
+Under `RUBY_ENGINE == "opal"`, Moxml's default adapter is `:oga` (see
+<<Default adapter selection>>). Oga is a pure-Ruby XML parser; under
+standard CRuby its lexer and parsers are accelerated by the `liboga`
+and `libll` C extensions. Those extensions cannot be compiled into
+JavaScript, so on Opal they are replaced by the pure-Ruby fallbacks
+shipped in `ext/pureruby/` of the Opal-compatible forks below.
+
+The REXML adapter is also available on Opal (`Moxml.new(:rexml)`) but
+relies on a number of compatibility shims because REXML uses Ruby
+regular-expression features (the `/n` flag, `\u{...}` codepoint
+escapes, inline flag groups) and String APIs that do not all transpile
+to JavaScript today. `:oga` is the recommended path for new Opal
+projects.
+
+=== Required XML library forks
+
+Upstream https://github.com/yorickpeterse/oga[oga] and
+https://github.com/yorickpeterse/ruby-ll[ruby-ll] do not currently
+ship Opal-compatible fallbacks. Moxml vendors the following forks:
+
+* https://github.com/lutaml/opal-oga[lutaml/opal-oga] — oga with an
+  `ext/pureruby/oga/native/lexer.rb` fallback that fires when
+  `RUBY_PLATFORM == 'opal'`. Under CRuby/JRuby the fork behaves
+  identically to upstream oga.
+* https://github.com/lutaml/opal-ruby-ll[lutaml/opal-ruby-ll] —
+  ruby-ll with `ext/pureruby/ll/native/{driver,driver_config}.rb`
+  fallbacks selected by the same conditional in `lib/ll/setup.rb`.
+
+Both forks are vendored as submodules under `vendor/opal-oga` and
+`vendor/opal-ruby-ll` in the Moxml repository. Moxml's own `Gemfile`
+references them via `path:` source so that any consumer of Moxml under
+Opal resolves to the same fork commits Moxml was tested against.
+
+=== Wiring the forks in a downstream Gemfile
+
+Downstream libraries that run on Opal (for example
+https://github.com/plurimath/plurimath-js[plurimath-js]) must also use
+the Opal-compatible forks rather than upstream `oga` and `ruby-ll`.
+Wire them as `path:` or `git:` sources so the fork's
+`RUBY_PLATFORM == 'opal'` conditional can fire:
+
+[source,ruby]
+----
+# In your downstream gem's Gemfile (or gemspec)
+gem "moxml",    "~> 0.1.24"        # provides the :oga adapter
+gem "oga",      git: "https://github.com/lutaml/opal-oga.git",
+                ref: "<commit-sha-moxml-tests-against>"
+gem "ruby-ll",  git: "https://github.com/lutaml/opal-ruby-ll.git",
+                ref: "<commit-sha-moxml-tests-against>"
+----
+
+Pin the `ref:` to the submodule commits Moxml ships in
+`vendor/opal-oga` and `vendor/opal-ruby-ll` (recorded in
+`.gitmodules`) so your fork and Moxml's fork stay in lockstep. If you
+prefer to vendor the forks yourself, replace the `git:` source with
+`path: "vendor/opal-oga"` and `path: "vendor/opal-ruby-ll"` after
+copying them in.
+
+=== Opal build configuration
+
+Under Opal, the forks' `lib/` directory is on the load path (via the
+gem), but the pure-Ruby implementations live under `ext/pureruby/`.
+That directory must be added to Opal's load path so the
+`if RUBY_PLATFORM == 'opal'` branch in `lib/oga.rb` and
+`lib/ll/setup.rb` resolves to the pure-Ruby files instead of trying to
+load the C extension.
+
+For consumers using https://github.com/opal/opal[Opal] directly:
+
+[source,ruby]
+----
+require "opal"
+
+# Opal path: put both lib/ and ext/pureruby/ on the load path so the
+# fork's conditional requires resolve to the pure-Ruby fallback.
+%w[opal-oga opal-ruby-ll].each do |fork|
+  Opal.append_path File.expand_path("vendor/#{fork}/lib", __dir__)
+  Opal.append_path File.expand_path("vendor/#{fork}/ext/pureruby", __dir__)
+end
+
+# Moxml's Opal boot file (lib/compat/opal/moxml_boot.rb) explicitly
+# requires every module that would normally be autoloaded under CRuby.
+require "moxml_boot"
+----
+
+For consumers using https://github.com/opal/opal-compiler[Opal via
+Sprockets/Webpack], the equivalent is to add both `lib/` and
+`ext/pureruby/` from each fork to the Opal `paths` array.
+
+=== Verifying the Opal build
+
+Moxml's own Opal test suite exercises the wiring described above. To
+reproduce:
+
+[source,shell]
+----
+# One-time setup: install ragel + ruby-ll so the forks' gitignored
+# generated lexer/parser sources can be produced.
+gem install ruby-ll --no-document
+# (Install ragel via your package manager, e.g. apt-get install ragel
+#  or brew install ragel.)
+
+# Generate the gitignored outputs in the vendored forks.
+bundle exec rake vendor:prepare
+
+# Run the Opal (JavaScript) test suite.
+bundle exec rake spec:opal
+----
+
+Reference implementation: https://github.com/plurimath/plurimath-js[plurimath-js]
+is the canonical downstream consumer; its `Rakefile` and `env/` wrapper
+scripts show the full pattern end-to-end.
+
+
 == Specific adapter limitations
 
 === Ox adapter

data/Rakefile

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+# vendor:prepare must be runnable before `bundle install` (CI runs it
+# first so the path-source oga/ruby-ll forks' gitignored lexer/parser
+# outputs exist before their extconf.rb runs). Guard the rspec/opal
+# requires so the file loads with only `rake` + `bundler` available.
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+end
 
 begin
   require "opal/rspec/rake_task"
@@ -17,15 +24,110 @@ begin
       File.exist?(File.join(p, "rexml", "document.rb"))
     end
     Opal.append_path rexml_lib if rexml_lib
+
+    # The Opal-compatible oga and ruby-ll forks (vendored as submodules)
+    # expose pure-Ruby implementations under ext/pureruby/. Their top-level
+    # lib/oga.rb and lib/ll/setup.rb conditionally require them when
+    # RUBY_PLATFORM == 'opal'. Both lib/ and ext/pureruby/ must be on
+    # Opal's load path so the conditional resolves correctly.
+    %w[opal-oga opal-ruby-ll].each do |fork_name|
+      fork_path = File.expand_path("vendor/#{fork_name}", __dir__)
+      Opal.append_path File.join(fork_path, "lib")
+      Opal.append_path File.join(fork_path, "ext/pureruby")
+    end
   end
 rescue LoadError
   # Opal not available or incompatible with current Ruby version
 end
 
-require "rubocop/rake_task"
+begin
+  require "rubocop/rake_task"
+  RuboCop::RakeTask.new
+rescue LoadError
+end
+
+# Regenerate the ragel / ruby-ll outputs that the Opal-compatible forks
+# (vendored as submodules under vendor/) gitignore. The forks ship the
+# grammar sources (.rl / .rll) but not the generated .rb / .c, since
+# those are large and version-controllable upstream. Both ragel and
+# ruby-ll must be on PATH; the upstream ruby-ll gem is sufficient for
+# generation (the fork is only needed at runtime).
+namespace :vendor do
+  desc "Generate ragel / ruby-ll outputs in vendored opal-oga and opal-ruby-ll"
+  task :prepare do
+    require "fileutils"
+
+    oga = File.expand_path("vendor/opal-oga", __dir__)
+    ruby_ll = File.expand_path("vendor/opal-ruby-ll", __dir__)
+
+    generators = [
+      # oga: ruby-ll grammar → Ruby parser
+      ["ruby-ll #{oga}/lib/oga/xml/parser.rll -o #{oga}/lib/oga/xml/parser.rb",
+       "#{oga}/lib/oga/xml/parser.rb",
+       "#{oga}/lib/oga/xml/parser.rll"],
+      ["ruby-ll #{oga}/lib/oga/xpath/parser.rll -o #{oga}/lib/oga/xpath/parser.rb",
+       "#{oga}/lib/oga/xpath/parser.rb",
+       "#{oga}/lib/oga/xpath/parser.rll"],
+      ["ruby-ll #{oga}/lib/oga/css/parser.rll -o #{oga}/lib/oga/css/parser.rb",
+       "#{oga}/lib/oga/css/parser.rb",
+       "#{oga}/lib/oga/css/parser.rll"],
+      # oga: ragel Ruby lexer
+      ["ragel -R -F1 #{oga}/lib/oga/xpath/lexer.rl -o #{oga}/lib/oga/xpath/lexer.rb",
+       "#{oga}/lib/oga/xpath/lexer.rb",
+       "#{oga}/lib/oga/xpath/lexer.rl"],
+      ["ragel -R -F1 #{oga}/lib/oga/css/lexer.rl -o #{oga}/lib/oga/css/lexer.rb",
+       "#{oga}/lib/oga/css/lexer.rb",
+       "#{oga}/lib/oga/css/lexer.rl"],
+      # oga: ragel C lexer for liboga
+      ["ragel -C -I #{oga}/ext/ragel -G2 #{oga}/ext/c/lexer.rl -o #{oga}/ext/c/lexer.c",
+       "#{oga}/ext/c/lexer.c",
+       "#{oga}/ext/c/lexer.rl"],
+      # ruby-ll: ruby-ll grammar → Ruby parser
+      ["ruby-ll #{ruby_ll}/lib/ll/parser.rll -o #{ruby_ll}/lib/ll/parser.rb --no-requires",
+       "#{ruby_ll}/lib/ll/parser.rb",
+       "#{ruby_ll}/lib/ll/parser.rll"],
+    ]
 
-RuboCop::RakeTask.new
+    generators.each do |cmd, output, source|
+      if File.exist?(output) && File.mtime(output) >= File.mtime(source)
+        next
+      end
 
+      FileUtils.mkdir_p(File.dirname(output))
+      sh cmd
+    end
+  end
+
+  # Bundler does not reliably compile native extensions for path-source
+  # gems. Build liboga/libll explicitly so `require "oga"` resolves.
+  desc "Compile liboga / libll native extensions for vendored forks"
+  task :compile do
+    require "fileutils"
+    require "rbconfig"
+
+    dlext = RbConfig::CONFIG["DLEXT"]
+
+    {
+      "vendor/opal-ruby-ll" => "libll",
+      "vendor/opal-oga" => "liboga",
+    }.each do |fork_path, ext_name|
+      abs_fork = File.expand_path(fork_path, __dir__)
+      lib_bundle = File.join(abs_fork, "lib", "#{ext_name}.#{dlext}")
+      ext_dir = File.join(abs_fork, "ext", "c")
+      extconf = File.join(ext_dir, "extconf.rb")
+      lib_dir = File.join(abs_fork, "lib")
+      next if File.exist?(lib_bundle)
+
+      Dir.chdir(ext_dir) do
+        sh "ruby #{extconf}"
+        sh "make"
+        FileUtils.cp("#{ext_name}.#{dlext}", lib_dir)
+      end
+    end
+  end
+end
+
+if defined?(RSpec)
 namespace :spec do
   if defined?(Opal::RSpec::RakeTask)
     desc "Run Opal (JavaScript) tests"
@@ -34,12 +136,21 @@ namespace :spec do
       server.append_path "spec"
 
       runner.default_path = "spec"
+      # `oga` and `ll/setup` must be required before moxml_boot so that
+      # the forks' Opal-aware conditional requires fire (lib/oga.rb calls
+      # `require 'oga/native/lexer'` when RUBY_PLATFORM == 'opal'; that
+      # resolves against vendor/opal-oga/ext/pureruby/, which the global
+      # Opal.append_path calls above add to the load path).
       runner.requires = %w[rexml_compat rexml/document rexml/xpath
+                           oga ll/setup
                            moxml_boot spec_helper support/opal]
       runner.files = Dir.glob("spec/moxml/*opal*_spec.rb") +
         Dir.glob("spec/moxml/native_attachment/opal_spec.rb") +
         Dir.glob("spec/moxml/adapter/shared_examples/*.rb")
     end
+
+    desc "Alias for spec:opal that also runs vendor:prepare"
+    task opal: "vendor:prepare"
   end
 
   desc "Validate XML fixtures are well-formed (requires xmllint)"
@@ -124,6 +235,7 @@ namespace :spec do
   task all: %i[unit adapter integration consistency examples
                performance]
 end
+end
 
 namespace :benchmark do
   desc "Run XPath performance benchmarks"

data/lib/compat/opal/moxml_boot.rb

@@ -35,6 +35,10 @@ require "moxml/sax/element_handler"
 require "moxml/sax/block_handler"
 require "moxml/sax/namespace_splitter"
 require "moxml/adapter/rexml"
+require "moxml/adapter/customized_oga"
+require "moxml/adapter/customized_oga/xml_declaration"
+require "moxml/adapter/customized_oga/xml_generator"
+require "moxml/adapter/oga"
 require "moxml/document_builder"
 require "moxml/builder"
 require "moxml/context"

data/lib/moxml/adapter.rb

@@ -11,9 +11,11 @@ module Moxml
     AVAILABLE_ADAPTERS = %i[nokogiri oga rexml ox headed_ox libxml].freeze
 
     # Adapters that work under the Opal (JavaScript) runtime.
-    # REXML is pure Ruby and Opal reimplements strscan/stringio in its stdlib,
-    # enabling REXML to compile cleanly to JavaScript.
-    OPAL_AVAILABLE_ADAPTERS = %i[rexml].freeze
+    # Oga is pure Ruby and designed with Opal compatibility in mind — it is the
+    # canonical XML parser for the JavaScript runtime. REXML is also pure Ruby
+    # but requires extensive runtime compat shims (regex features like /n,
+    # \u{...}, (?-mix:...) don't transpile cleanly), so it is opt-in only.
+    OPAL_AVAILABLE_ADAPTERS = %i[oga rexml].freeze
 
     # Registry mapping adapter names to their class name suffixes.
     # Special cases (like :headed_ox → "HeadedOx") live here instead of

data/lib/moxml/config.rb

@@ -7,7 +7,7 @@ module Moxml
     VALID_LINE_ENDINGS = [LINE_ENDING_LF, LINE_ENDING_CRLF].freeze
     VALID_ADAPTERS = %i[nokogiri oga rexml ox headed_ox libxml].freeze
     DEFAULT_ADAPTER = :nokogiri
-    OPAL_DEFAULT_ADAPTER = :rexml
+    OPAL_DEFAULT_ADAPTER = :oga
 
     # Entity loading modes:
     # - :required - Must load entities, raise error if unavailable (default)

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.1.24"
+  VERSION = "0.1.25"
 end

data/moxml.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   # RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject do |f|
-      f.match(%r{^(test|features)/})
+      f.match(%r{^(test|features|vendor/)})
     end
   end
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

data/spec/moxml/adapter/platform_spec.rb

@@ -2,69 +2,87 @@
 
 require "spec_helper"
 
-RSpec.describe Moxml::Adapter, ".platform_adapters" do
-  it "includes all known adapters under MRI" do
-    expect(described_class.platform_adapters).to include(:nokogiri, :oga,
-                                                         :rexml, :ox)
-  end
-
-  it "uses the AVAILABLE_ADAPTERS constant under MRI" do
-    expect(described_class.platform_adapters).to eq(Moxml::Adapter::AVAILABLE_ADAPTERS)
-  end
-end
-
-RSpec.describe Moxml::Adapter, ".available?" do
-  it "returns true for :oga" do
-    expect(described_class.available?(:oga)).to be true
-  end
+RSpec.describe Moxml::Adapter do
+  describe ".platform_adapters" do
+    it "includes all known adapters under MRI" do
+      expect(described_class.platform_adapters).to include(:nokogiri, :oga,
+                                                           :rexml, :ox)
+    end
 
-  it "returns true for :nokogiri under MRI" do
-    expect(described_class.available?(:nokogiri)).to be true
+    it "uses the AVAILABLE_ADAPTERS constant under MRI" do
+      expect(described_class.platform_adapters).to eq(Moxml::Adapter::AVAILABLE_ADAPTERS)
+    end
   end
 
-  context "when Opal platform adapters are in effect" do
-    before do
-      allow(described_class).to receive(:platform_adapters)
-        .and_return(Moxml::Adapter::OPAL_AVAILABLE_ADAPTERS)
+  describe ".available?" do
+    it "returns true for :oga" do
+      expect(described_class.available?(:oga)).to be true
     end
 
-    it "returns false for :nokogiri" do
-      expect(described_class.available?(:nokogiri)).to be false
+    it "returns true for :nokogiri under MRI" do
+      expect(described_class.available?(:nokogiri)).to be true
     end
 
-    it "returns true for :rexml" do
-      expect(described_class.available?(:rexml)).to be true
+    context "when Opal platform adapters are in effect" do
+      before do
+        allow(described_class).to receive(:platform_adapters)
+          .and_return(Moxml::Adapter::OPAL_AVAILABLE_ADAPTERS)
+      end
+
+      it "returns false for :nokogiri" do
+        expect(described_class.available?(:nokogiri)).to be false
+      end
+
+      it "returns true for :oga" do
+        expect(described_class.available?(:oga)).to be true
+      end
+
+      it "returns true for :rexml" do
+        expect(described_class.available?(:rexml)).to be true
+      end
     end
   end
-end
 
-RSpec.describe Moxml::Adapter, ".load" do
-  context "when Opal platform adapters are in effect" do
-    before do
-      allow(described_class).to receive(:platform_adapters)
-        .and_return(Moxml::Adapter::OPAL_AVAILABLE_ADAPTERS)
-    end
+  describe ".load" do
+    context "when Opal platform adapters are in effect" do
+      before do
+        allow(described_class).to receive(:platform_adapters)
+          .and_return(Moxml::Adapter::OPAL_AVAILABLE_ADAPTERS)
+      end
 
-    it "raises AdapterError for :nokogiri" do
-      expect { described_class.load(:nokogiri) }.to raise_error(
-        Moxml::AdapterError, /not available on this platform/
-      )
+      it "raises AdapterError for :nokogiri" do
+        expect { described_class.load(:nokogiri) }.to raise_error(
+          Moxml::AdapterError, /not available on this platform/
+        )
+      end
     end
   end
-end
 
-RSpec.describe "Moxml::Adapter::OPAL_AVAILABLE_ADAPTERS" do
-  it "contains only :rexml" do
-    expect(Moxml::Adapter::OPAL_AVAILABLE_ADAPTERS).to eq(%i[rexml])
+  describe "OPAL_AVAILABLE_ADAPTERS" do
+    it "lists :oga as the primary Opal adapter, with :rexml as opt-in" do
+      expect(Moxml::Adapter::OPAL_AVAILABLE_ADAPTERS).to eq(%i[oga rexml])
+    end
   end
-end
 
-RSpec.describe "Moxml::Adapter::CONST_NAME_MAP" do
-  it "maps :headed_ox to HeadedOx" do
-    expect(Moxml::Adapter::CONST_NAME_MAP[:headed_ox]).to eq("HeadedOx")
+  describe "CONST_NAME_MAP" do
+    it "maps :headed_ox to HeadedOx" do
+      expect(Moxml::Adapter::CONST_NAME_MAP[:headed_ox]).to eq("HeadedOx")
+    end
+
+    it "falls back to capitalize for unmapped adapters" do
+      expect(Moxml::Adapter::CONST_NAME_MAP[:nokogiri]).to be_nil
+    end
   end
 
-  it "falls back to capitalize for unmapped adapters" do
-    expect(Moxml::Adapter::CONST_NAME_MAP[:nokogiri]).to be_nil
+  describe "default adapter / available list invariants" do
+    it "DEFAULT_ADAPTER is a member of AVAILABLE_ADAPTERS" do
+      expect(Moxml::Adapter::AVAILABLE_ADAPTERS)
+        .to include(Moxml::Config::DEFAULT_ADAPTER)
+    end
+
+    it "OPAL_DEFAULT_ADAPTER is a member of OPAL_AVAILABLE_ADAPTERS" do
+      expect(Moxml::Adapter::OPAL_AVAILABLE_ADAPTERS)
+        .to include(Moxml::Config::OPAL_DEFAULT_ADAPTER)
+    end
   end
 end

data/spec/moxml/opal_oga_adapter_spec.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "moxml/adapter/shared_examples/adapter_contract"
+
+RSpec.describe Moxml::Adapter::Oga, if: RUBY_ENGINE == "opal" do
+  around do |example|
+    Moxml.with_config(:oga, true, "UTF-8") do
+      example.run
+    end
+  end
+
+  it_behaves_like "xml adapter"
+end

data/spec/moxml/opal_oga_features_spec.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Exercises feature areas under Opal that are not covered by the shared
+# adapter contract (opal_oga_adapter_spec.rb) or the basic smoke spec
+# (opal_oga_smoke_spec.rb). Targets the default Opal adapter (:oga).
+# Uses an explicit :oga context so leaked global config from other specs
+# cannot flip the adapter under test.
+RSpec.describe "Moxml Opal oga feature coverage", if: RUBY_ENGINE == "opal" do
+  let(:context) { Moxml.new(:oga) }
+
+  describe "builder DSL" do
+    it "builds a document with the block DSL" do
+      doc = Moxml::Builder.new(context).build do
+        root do
+          child "text"
+        end
+      end
+
+      expect(doc.root.name).to eq("root")
+      expect(doc.root.children.first.name).to eq("child")
+      expect(doc.root.children.first.text).to eq("text")
+    end
+
+    it "creates nested elements via blocks" do
+      doc = Moxml::Builder.new(context).build do
+        library do
+          book(id: "1") { title "A" }
+          book(id: "2") { title "B" }
+        end
+      end
+
+      books = doc.root.children.grep(Moxml::Element)
+      expect(books.length).to eq(2)
+      expect(books.map { |b| b["id"] }).to eq(%w[1 2])
+    end
+
+    it "supports method_missing DSL with attributes and text" do
+      doc = Moxml::Builder.new(context).build do
+        person(name: "Alice", age: "30") { email "alice@example.com" }
+      end
+
+      person = doc.root
+      expect(person.name).to eq("person")
+      expect(person["name"]).to eq("Alice")
+      expect(person["age"]).to eq("30")
+      expect(person.children.first.name).to eq("email")
+      expect(person.children.first.text).to eq("alice@example.com")
+    end
+
+    it "strips trailing underscore for reserved-name tags" do
+      doc = Moxml::Builder.new(context).build do
+        class_ { name "Foo" }
+      end
+
+      expect(doc.root.name).to eq("class")
+    end
+
+    it "attaches namespace declarations" do
+      builder = Moxml::Builder.new(context)
+      doc = builder.build do
+        root("xmlns:dc": "http://purl.org/dc/elements/1.1/") do
+          builder.element("dc:title") { builder.text "Hello" }
+        end
+      end
+
+      title = doc.root.children.find { |c| c.is_a?(Moxml::Element) }
+      expect(title.name).to eq("dc:title")
+      expect(doc.to_xml).to include("xmlns:dc")
+      expect(doc.to_xml).to include("dc:title")
+    end
+  end
+
+  describe "XML declaration preservation" do
+    it "does not add a declaration when the input has none" do
+      doc = context.parse("<root><child/></root>")
+      output = doc.to_xml
+
+      expect(output).not_to include("<?xml")
+      expect(doc.has_xml_declaration).to be false
+    end
+
+    it "preserves the declaration when the input has one" do
+      xml = '<?xml version="1.0" encoding="UTF-8"?><root/>'
+      doc = context.parse(xml)
+
+      expect(doc.has_xml_declaration).to be true
+      expect(doc.to_xml).to include("<?xml")
+      expect(doc.to_xml).to include('version="1.0"')
+    end
+
+    it "forces the declaration on with declaration: true" do
+      doc = context.parse("<root/>")
+      expect(doc.to_xml(declaration: true)).to include("<?xml")
+    end
+
+    it "forces the declaration off with declaration: false" do
+      doc = context.parse('<?xml version="1.0"?><root/>')
+      expect(doc.to_xml(declaration: false)).not_to include("<?xml")
+    end
+
+    it "preserves standalone attribute" do
+      xml = '<?xml version="1.0" standalone="yes"?><root/>'
+      doc = context.parse(xml)
+      expect(doc.to_xml).to include("standalone")
+    end
+  end
+
+  describe "doctype handling" do
+    it "parses a SIMPLE doctype" do
+      doc = context.parse("<!DOCTYPE root><root/>")
+      doctype = doc.children.find { |c| c.is_a?(Moxml::Doctype) }
+      expect(doctype).not_to be_nil
+      expect(doctype.name).to eq("root")
+    end
+
+    it "parses a PUBLIC doctype with external and system ids" do
+      xml = '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><html/>'
+      doc = context.parse(xml)
+      doctype = doc.children.find { |c| c.is_a?(Moxml::Doctype) }
+
+      expect(doctype).not_to be_nil
+      expect(doctype.name).to eq("html")
+      expect(doctype.external_id).to eq("-//W3C//DTD HTML 4.01//EN")
+      expect(doctype.system_id).to eq("http://www.w3.org/TR/html4/strict.dtd")
+    end
+
+    it "round-trips the doctype through serialization" do
+      xml = "<!DOCTYPE root><root/>"
+      doc = context.parse(xml)
+      expect(doc.to_xml).to include("DOCTYPE")
+      expect(doc.to_xml).to include("root")
+    end
+  end
+
+  describe "round-trip stability" do
+    it "round-trips a document with mixed content" do
+      xml = <<~XML.strip
+        <root attr="value">
+          <child>text</child>
+          <!-- comment -->
+          <nested><deep>data</deep></nested>
+        </root>
+      XML
+
+      doc1 = context.parse(xml)
+      serialized1 = doc1.to_xml
+      doc2 = context.parse(serialized1)
+      serialized2 = doc2.to_xml
+
+      expect(serialized2).to eq(serialized1)
+    end
+
+    it "round-trips a document with namespaces" do
+      xml = '<root xmlns:ns="http://example.com/ns"><ns:child>content</ns:child></root>'
+      doc1 = context.parse(xml)
+      serialized1 = doc1.to_xml
+
+      doc2 = context.parse(serialized1)
+      child = doc2.root.children.find { |c| c.is_a?(Moxml::Element) }
+      expect(child.name).to eq("child")
+      expect(child.namespace_prefix).to eq("ns")
+      expect(doc2.to_xml).to include("xmlns:ns")
+    end
+
+    it "round-trips a document with CDATA" do
+      xml = "<root><![CDATA[<unparsed>content</unparsed>]]></root>"
+      doc1 = context.parse(xml)
+      serialized1 = doc1.to_xml
+
+      expect(serialized1).to include("<![CDATA[")
+      doc2 = context.parse(serialized1)
+      expect(doc2.to_xml).to include("<![CDATA[")
+    end
+  end
+
+  describe "XPath under Opal" do
+    it "evaluates element-only XPath" do
+      doc = context.parse("<root><a><b>1</b></a><a><b>2</b></a></root>")
+      results = doc.xpath("//a/b")
+      expect(results.length).to eq(2)
+      expect(results.map(&:text)).to eq(%w[1 2])
+    end
+
+    it "supports attribute predicates" do
+      doc = context.parse('<root><item id="x">1</item><item id="y">2</item></root>')
+      found = doc.xpath("//item").find { |i| i["id"] == "y" }
+      expect(found.text).to eq("2")
+    end
+
+    it "supports at_xpath" do
+      doc = context.parse("<root><a>1</a><a>2</a></root>")
+      first = doc.at_xpath("//a")
+      expect(first.text).to eq("1")
+    end
+  end
+
+  describe "comment and processing instruction handling" do
+    it "preserves comments through parse/serialize" do
+      xml = "<root><!-- my comment --></root>"
+      doc = context.parse(xml)
+      expect(doc.to_xml).to include("my comment")
+    end
+
+    it "preserves processing instructions through parse/serialize" do
+      xml = "<?pi-target pi-data?><root/>"
+      doc = context.parse(xml)
+      expect(doc.to_xml).to include("pi-target")
+    end
+  end
+end

data/spec/moxml/opal_oga_smoke_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Verifies that the Opal default adapter (:oga, set in Moxml::Config)
+# loads correctly via the Opal-compatible oga fork. The fork's
+# lib/oga.rb dispatches `require 'liboga'` to `require 'oga/native/lexer'`
+# under Opal, which resolves to the pure-Ruby lexer vendored at
+# vendor/opal-oga/ext/pureruby/.
+RSpec.describe "Moxml Opal oga default", if: RUBY_ENGINE == "opal" do
+  let(:context) { Moxml.new }
+
+  it "defaults to :oga under Opal" do
+    expect(Moxml::Config::OPAL_DEFAULT_ADAPTER).to eq(:oga)
+  end
+
+  it "parses XML through the oga adapter" do
+    doc = context.parse("<root><child>text</child></root>")
+    expect(doc.root.name).to eq("root")
+    expect(doc.root.children.first.name).to eq("child")
+  end
+
+  it "decodes entities single-pass" do
+    doc = context.parse("<root>&amp;#38;</root>")
+    expect(doc.root.text).to eq("&#38;")
+  end
+
+  it "serializes back to XML" do
+    xml = '<person name="Alice"><age>30</age></person>'
+    doc = context.parse(xml)
+    serialized = doc.to_xml
+    expect(serialized).to include("person")
+    expect(serialized).to include("Alice")
+  end
+end

data/spec/moxml/xpath/functions/node_functions_spec.rb

@@ -57,7 +57,7 @@ RSpec.describe "XPath Node Functions" do
       result = proc.call(doc)
 
       # Depending on adapter, may include ns: prefix
-      expect(result).to match(/item/)
+      expect(result).to include("item")
     end
 
     it "returns empty string when no node matched" do

data/spec/spec_helper.rb

@@ -101,7 +101,7 @@ RSpec.configure do |config|
 end
 
 Moxml.configure do |config|
-  config.adapter = RUBY_ENGINE == "opal" ? :rexml : :nokogiri
+  config.adapter = RUBY_ENGINE == "opal" ? Moxml::Config::OPAL_DEFAULT_ADAPTER : Moxml::Config::DEFAULT_ADAPTER
   config.strict_parsing = true
   config.default_encoding = "UTF-8"
   config.entity_load_mode = :optional if RUBY_ENGINE == "opal"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.1.24
+  version: 0.1.25
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-02 00:00:00.000000000 Z
+date: 2026-06-26 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -28,6 +28,7 @@ files:
 - ".github/workflows/release.yml"
 - ".github/workflows/round-trip.yml"
 - ".gitignore"
+- ".gitmodules"
 - ".rspec"
 - ".rspec-opal"
 - ".rubocop.yml"
@@ -352,6 +353,9 @@ files:
 - spec/moxml/node_set_spec.rb
 - spec/moxml/node_spec.rb
 - spec/moxml/node_type_map_spec.rb
+- spec/moxml/opal_oga_adapter_spec.rb
+- spec/moxml/opal_oga_features_spec.rb
+- spec/moxml/opal_oga_smoke_spec.rb
 - spec/moxml/opal_rexml_adapter_spec.rb
 - spec/moxml/opal_smoke_spec.rb
 - spec/moxml/processing_instruction_spec.rb