moxml 0.5.145 → 0.5.147

data/lib/moxml/document.rb

@@ -73,6 +73,15 @@ module Moxml
       root_element ? Moxml::Node.wrap(root_element, context) : nil
     end
 
+    # Documents are container nodes: #text concatenates descendant
+    # text, Nokogiri's Document#text contract (issue #400) — the base
+    # Node#text answered "" and silently emptied consumers'
+    # content-preservation checks.
+    def text
+      val = adapter.text_content(@native)
+      entity_bearing? ? adapter.restore_entities(val) : val
+    end
+
     # Materialize the root subtree — see Moxml::Materializer.
     def materialize(&block)
       return to_enum(:materialize) unless block

data/lib/moxml/version.rb

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

data/lib/moxml/xpath/compiler.rb

@@ -40,6 +40,7 @@ module Moxml
       # @param namespaces [Hash, nil] Optional namespace prefix mappings
       # @return [Proc] Compiled Proc that accepts a document
       def self.compile_with_cache(ast, namespaces: nil)
+        namespaces = normalize_namespaces(namespaces)
         cache_key = namespaces ? [ast, namespaces] : ast
         CACHE.get_or_set(cache_key) { new(namespaces: namespaces).compile(ast) }
       end
@@ -48,12 +49,24 @@ module Moxml
       #
       # @param namespaces [Hash, nil] Optional namespace prefix mappings
       def initialize(namespaces: nil)
-        @namespaces = namespaces
+        @namespaces = self.class.normalize_namespaces(namespaces)
         @literal_id = 0
         @predicate_nodesets = []
         @predicate_indexes = []
       end
 
+      # Prefix lookups are string-keyed (the parser yields prefix
+      # strings); symbol-keyed bindings — the common Nokogiri spelling
+      # (`xpath("//cml:molecule", cml: URI)`) — must resolve too, or
+      # the miss falls through to prefix-spelling matching and
+      # namespaced elements never match (issue #395).
+      def self.normalize_namespaces(namespaces)
+        return nil if namespaces.nil?
+        return namespaces unless namespaces.is_a?(Hash)
+
+        namespaces.transform_keys(&:to_s)
+      end
+
       # Compiles an XPath AST into a Ruby Proc
       #
       # @param ast [AST::Node] XPath AST to compile

data/spec/consistency/divergence_register_spec.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Divergence register linkage (TODO.model/02): the register
+# (docs/_pages/divergences.adoc) and the consistency suite must stay
+# mechanically consistent — every capability-related skip cites a
+# register ID, every register entry is cited by at least one spec, and
+# no spec cites an unregistered ID.
+RSpec.describe "divergence register linkage" do
+  REGISTER_PATH = "docs/_pages/divergences.adoc" # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  SCAN_GLOBS = %w[spec/consistency/**/*.rb spec/moxml/**/*.rb].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  NEXT_GATE = [ # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    /same engine as/, # engine dedup, not a divergence
+    /source_adapter == target_adapter/, # self round-trip
+    /MAX_SIZE/, # size guard
+    /AVAILABLE_ADAPTERS\.include/, # availability filter
+    /skip_shapes/,              # shape routing (IDs cited above)
+    /leptris_fixed\?/,          # version gate
+    /source_elements/,          # data-presence guard
+    /next unless match/,        # scanner-internal guard
+  ].freeze
+
+  # Version/availability gates are not divergences: a binding too old
+  # or an adapter not installed is a deployment fact, not an
+  # engine-vs-model difference at equal versions.
+  GATE = [ # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    /unavailable/i, /not available/, /predates/, /not installed/i,
+    /not present/i, /requires/i, /required\z/, /has no \S+ face/,
+    /lacks the /, /carries /, /degraded below/, /lockstep/i,
+    /unreleased/i, /stood down/, /recovered without/,
+    /Only \S+ available in CI/i, /adapter-specific/i, /noblanks/,
+    /SKIP_ parse flags/, /engine < \d/
+  ].freeze
+
+  def register_ids
+    File.readlines(REGISTER_PATH)
+      .filter_map { |line| line[/\A\|\s*(D-\d+)\s*$/, 1] }
+      .uniq
+  end
+
+  def spec_files
+    SCAN_GLOBS.flat_map { |g| Dir[g] }.uniq
+  end
+
+  def cited_ids
+    spec_files.flat_map { |path| File.readlines(path) }
+      .flat_map { |line| line.scan(/D-\d+/) }
+      .uniq
+  end
+
+  it "has a register with entries" do
+    expect(register_ids).not_to be_empty
+  end
+
+  it "requires capability-related skips to cite a register ID" do
+    offenders = []
+    spec_files.each do |path|
+      File.readlines(path).each_with_index do |line, i|
+        next unless (msg = line[/skip\s+[&(]?\s*["'](.*?)["']/, 1])
+
+        next if GATE.any? { |re| re.match?(msg) }
+        next if msg.match?(/D-\d+/)
+
+        offenders << "#{path}:#{i + 1} #{msg.strip[0, 60]}"
+      end
+    end
+    expect(offenders).to be_empty,
+                         "capability skips must cite a divergence-register " \
+                         "ID (D-NN): #{offenders.join('; ')}"
+  end
+
+  it "requires adapter-exempting next-guards to cite a nearby register ID" do
+    offenders = []
+    spec_files.each do |path|
+      next if path.end_with?("divergence_register_spec.rb")
+
+      lines = File.readlines(path)
+      lines.each_with_index do |line, i|
+        next unless line.match?(/^\s*next\s+(if|unless)\s/)
+        next if NEXT_GATE.any? { |re| re.match?(line) }
+        next if line.match?(/D-\d+/)
+
+        context = lines[[i - 4, 0].max...i] + lines[(i + 1)..(i + 4)].to_a
+        next if context.any? { |l| l.match?(/D-\d+/) }
+
+        offenders << "#{path}:#{i + 1} #{line.strip[0, 60]}"
+      end
+    end
+    expect(offenders).to be_empty,
+                         "adapter-exempting next-guards must cite a " \
+                         "divergence-register ID (D-NN) on or above the " \
+                         "line: #{offenders.join('; ')}"
+  end
+
+  it "cites every register entry from at least one spec" do
+    missing = register_ids - cited_ids
+    expect(missing).to be_empty,
+                       "register entries never cited by a spec: " \
+                       "#{missing.join(', ')}"
+  end
+
+  it "never cites an unregistered divergence ID" do
+    orphans = cited_ids - register_ids
+    expect(orphans).to be_empty,
+                       "specs cite IDs missing from the register: " \
+                       "#{orphans.join(', ')}"
+  end
+end

data/spec/consistency/document_text_spec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Issue #400: documents are container nodes — Document#text
+# concatenates descendant text (Nokogiri's Document#text contract).
+# The base Node#text answered "" and silently emptied consumers'
+# content-preservation checks (canon's formatter asserted through
+# doc.text).
+RSpec.describe "Document#text concatenates descendant text" do
+  Moxml::Adapter::AVAILABLE_ADAPTERS.each do |adapter_name|
+    context "with #{adapter_name}" do
+      let(:ctx) { Moxml.new(adapter_name) }
+
+      it "answers the concatenated descendant text" do
+        doc = ctx.parse("<r><a>x</a><b>y</b></r>")
+        expect(doc.text).to eq("xy")
+      end
+
+      it "matches root.text (both containers recurse)" do
+        doc = ctx.parse("<r><a>x</a><b>y</b></r>")
+        expect(doc.text).to eq(doc.root.text)
+      end
+
+      it "answers an empty string for element-free documents" do
+        expect(ctx.parse("<r/>").text).to eq("")
+      end
+    end
+  end
+end

data/spec/consistency/eol_normalization_spec.rb

@@ -20,7 +20,7 @@ require "spec_helper"
 #                     binding release vending that engine rides
 #                     (gate: binding 1.9.240).
 RSpec.describe "XML line-ending normalization" do
-  ADAPTERS = %i[leptris nokogiri ox oga rexml libxml].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  EOL_NORMALIZATION_ADAPTERS = %i[leptris nokogiri ox oga rexml libxml].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
 
   def with_adapter(name)
     ctx = Moxml.new(name)
@@ -37,10 +37,10 @@ RSpec.describe "XML line-ending normalization" do
   end
 
   it "normalizes CRLF and lone CR to LF in text content" do
-    ADAPTERS.each do |name|
+    EOL_NORMALIZATION_ADAPTERS.each do |name|
       next unless leptris_fixed?(name)
 
-      skip "oga preserves raw CR (upstream)" if name == :oga
+      skip "D-02: oga preserves raw CR (upstream)" if name == :oga
 
       with_adapter(name) do |ctx|
         text = ctx.parse("<r>a\r\nb\rc</r>").root.children.first
@@ -50,10 +50,10 @@ RSpec.describe "XML line-ending normalization" do
   end
 
   it "normalizes EOL inside CDATA content" do
-    ADAPTERS.each do |name|
+    EOL_NORMALIZATION_ADAPTERS.each do |name|
       next unless leptris_fixed?(name)
 
-      skip "oga preserves raw CR (upstream)" if name == :oga
+      skip "D-02: oga preserves raw CR (upstream)" if name == :oga
 
       with_adapter(name) do |ctx|
         cdata = ctx.parse("<r><![CDATA[a\r\nb]]></r>").root.children.first
@@ -63,11 +63,11 @@ RSpec.describe "XML line-ending normalization" do
   end
 
   it "preserves CR from character references" do
-    ADAPTERS.each do |name|
+    EOL_NORMALIZATION_ADAPTERS.each do |name|
       next unless leptris_fixed?(name)
 
-      skip "ox collapses &#13; to LF (upstream)" if name == :ox
-      skip "oga preserves raw CR (upstream)" if name == :oga
+      skip "D-03: ox collapses &#13; to LF (upstream)" if name == :ox
+      skip "D-02: oga preserves raw CR (upstream)" if name == :oga
 
       with_adapter(name) do |ctx|
         text = ctx.parse("<r>a&#13;b</r>").root.children.first

data/spec/consistency/loud_degradation_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Loud degradation (processing model, "Errors and loud degradation"):
+# a capability an engine cannot deliver must answer the contract or
+# raise the named error — never a divergent answer. Probed across all
+# available adapters; the capability lists mirror the adapters'
+# actual engine backing.
+RSpec.describe "loud capability contracts" do
+  available = Moxml::Adapter::AVAILABLE_ADAPTERS
+  xslt_capable = %i[nokogiri leptris] & available
+  html_capable = %i[nokogiri leptris] & available
+
+  let(:sheet) do
+    %(<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">) \
+      "<xsl:template match='/'><o/></xsl:template></xsl:stylesheet>"
+  end
+
+  (available - xslt_capable).each do |name|
+    it "raises NotImplementedError for XSLT on #{name}" do
+      ctx = Moxml.new(name)
+      expect { ctx.xslt(sheet) }.to raise_error(Moxml::NotImplementedError)
+    end
+  end
+
+  (available - html_capable).each do |name|
+    it "raises NotImplementedError for to_xhtml on #{name}" do
+      doc = Moxml.new(name).parse("<r><a/></r>")
+      expect { doc.to_xhtml }.to raise_error(Moxml::NotImplementedError)
+    end
+
+    it "raises AdapterError for to_html on #{name}" do
+      doc = Moxml.new(name).parse("<r><a/></r>")
+      expect { doc.to_html }.to raise_error(Moxml::AdapterError)
+    end
+  end
+
+  xslt_capable.each do |name|
+    it "compiles a stylesheet on #{name}" do
+      expect(Moxml.new(name).xslt(sheet)).to be_a(Moxml::XSLT::Stylesheet)
+    end
+  end
+end

data/spec/consistency/model_coverage_audit_spec.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Model coverage matrix (TODO.model/03): every face family of the
+# processing model is governed for every adapter — covered by a pin
+# (the consistency/contract spec that asserts equivalence), exempt via
+# a registered divergence (adapter => D-ID), or loud (adapter =>
+# the named error class). An unpinned family is an ungoverned cell:
+# this audit fails until it has one of the three.
+# See docs/_references/processing-model.adoc for the model itself.
+RSpec.describe "model coverage matrix" do
+  MODEL_MATRIX = { # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+    "document order and children listing" => {
+      pin: "spec/consistency/adapter_parity_spec.rb",
+    },
+    "name resolution" => {
+      pin: "spec/consistency/xpath_idioms_spec.rb",
+    },
+    "namespace resolution and bindings normalization" => {
+      pin: "spec/consistency/xpath_idioms_spec.rb",
+    },
+    "attribute access" => {
+      pin: "spec/moxml/attribute_resolver_spec.rb",
+    },
+    "text/content/raw_content" => {
+      pin: "spec/moxml/text_spec.rb",
+    },
+    "parsing modes and diagnostics" => {
+      pin: "spec/moxml/document_parse_diagnostics_spec.rb",
+    },
+    "EOL normalization" => {
+      pin: "spec/consistency/eol_normalization_spec.rb",
+      exempt: { oga: "D-02", ox: "D-03" },
+    },
+    "entity modes" => {
+      pin: "spec/moxml/entity_spec.rb",
+    },
+    "XPath evaluation and declared idioms" => {
+      pin: "spec/consistency/xpath_idioms_spec.rb",
+      exempt: { oga: "D-01" },
+    },
+    "serialization shapes (xml/html/xhtml)" => {
+      pin: "spec/moxml/xhtml_output_spec.rb",
+    },
+    "indentation knobs" => {
+      pin: "spec/moxml/to_html_spec.rb",
+      exempt: { oga: "D-09", ox: "D-09", headed_ox: "D-09",
+                libxml: "D-09", leptris: "D-09" },
+    },
+    "canonicalization" => {
+      pin: "spec/moxml/c14n/adapter_delegation_spec.rb",
+      exempt: { oga: "D-04", ox: "D-05", headed_ox: "D-05" },
+    },
+    "XSLT" => {
+      pin: "spec/consistency/xslt_spec.rb",
+      loud: { oga: "Moxml::NotImplementedError",
+              ox: "Moxml::NotImplementedError",
+              headed_ox: "Moxml::NotImplementedError",
+              rexml: "Moxml::NotImplementedError",
+              libxml: "Moxml::NotImplementedError" },
+    },
+    "SAX" => {
+      pin: "spec/moxml/sax_spec.rb",
+    },
+    "materialization" => {
+      pin: "spec/moxml/plan_conformance_spec.rb",
+    },
+    "loud capability contracts" => {
+      pin: "spec/consistency/loud_degradation_spec.rb",
+    },
+  }.freeze
+
+  def register_ids
+    File.readlines("docs/_pages/divergences.adoc")
+      .filter_map { |line| line[/\A\|\s*(D-\d+)\s*$/, 1] }
+      .uniq
+  end
+
+  it "governs every face family with a pin" do
+    unpinned = MODEL_MATRIX.reject { |_, cell| cell[:pin] }.keys
+    expect(unpinned).to be_empty,
+                        "ungoverned face families (no pin): " \
+                        "#{unpinned.join(', ')}"
+  end
+
+  it "points every pin at an existing spec" do
+    missing = MODEL_MATRIX.filter_map do |family, cell|
+      family unless cell[:pin] && File.exist?(cell[:pin])
+    end
+    expect(missing).to be_empty, "pins missing on disk: #{missing.join(', ')}"
+  end
+
+  it "exempts adapters only via registered divergences" do
+    unknown = MODEL_MATRIX.flat_map do |family, cell|
+      (cell[:exempt] || {}).filter_map do |adapter, id|
+        "#{family}: #{adapter} -> #{id}" unless register_ids.include?(id)
+      end
+    end
+    expect(unknown).to be_empty,
+                       "exemptions cite unregistered IDs: #{unknown.join('; ')}"
+  end
+
+  it "declares loud cells only with named Moxml errors" do
+    bad = MODEL_MATRIX.flat_map do |family, cell|
+      (cell[:loud] || {}).filter_map do |adapter, error|
+        "#{family}: #{adapter} -> #{error}" unless error.start_with?("Moxml::")
+      end
+    end
+    expect(bad).to be_empty,
+                   "loud cells must name Moxml errors: #{bad.join('; ')}"
+  end
+end

data/spec/consistency/spec_constant_uniqueness_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Checker integrity (TODO.model/06): top-level constant names in spec
+# files all resolve through Object inside example blocks, so the same
+# name defined by two files makes the last-loaded file win — the 0.5.143
+# CORPUS collision made the battery fail ~50% of runs with a foreign
+# corpus. This guard kills the class.
+RSpec.describe "spec-file top-level constant uniqueness" do
+  it "defines each constant name in at most one spec/support file" do
+    seen = {}
+
+    Dir["spec/**/*.rb"].each do |path|
+      File.readlines(path).each_with_index do |line, i|
+        match = line.match(/\A\s*([A-Z][A-Z0-9_]*)\s*=[^=]/)
+        next unless match
+
+        name = match[1]
+        expect(seen)
+          .not_to have_key(name),
+                  "#{name} defined at #{seen[name]} and #{path}:#{i + 1} " \
+                  "— constants inside example blocks collide through " \
+                  "Object; give one file a unique name"
+        seen[name] = "#{path}:#{i + 1}"
+      end
+    end
+  end
+end

data/spec/consistency/xpath_idioms_spec.rb

@@ -11,11 +11,22 @@ require "spec_helper"
 # - Attribute-terminal steps work in every path position
 #   (leptris-ruby#458's table: //a/@id, //@id, r/a/@id,
 #   //*[f()]/@id — fixed by the engine's VM path work).
+CML_NS = "http://www.xml-cml.org/schema"
+ACI_NS = "http://www.xml-cml.org/schema/asciichem"
+
 RSpec.describe "XPath idioms across adapters" do
   let(:default_ns_xml) do
     '<svgmap xmlns="http://www.example.org/doc"><target href="a"/></svgmap>'
   end
   let(:plain_xml) { '<r><a id="x"><b/></a></r>' }
+  let(:cml_xml) do
+    <<~XML
+      <molecule xmlns="#{CML_NS}" xmlns:aci="#{ACI_NS}" id="m1">
+        <atomArray><atom id="a1"/></atomArray>
+        <aci:group multiplicity="2" bracket="paren" atomRefs="a1"/>
+      </molecule>
+    XML
+  end
 
   Moxml::Adapter::AVAILABLE_ADAPTERS.each do |adapter_name|
     next if adapter_name == :headed_ox # same engine as :ox
@@ -31,7 +42,7 @@ RSpec.describe "XPath idioms across adapters" do
         if adapter_name == :oga
           # oga's own Ruby XPath engine has no xmlns: default-ns
           # support (third-party; explicit bindings work).
-          skip "oga's XPath engine does not implement the xmlns: idiom"
+          skip "D-01: oga's XPath engine does not implement the xmlns: idiom"
         end
       end
 
@@ -56,6 +67,26 @@ RSpec.describe "XPath idioms across adapters" do
         expect(doc.xpath("//*[local-name()='a']/@id").first&.value).to eq("x")
       end
 
+      # Issue #395: bindings hashes arrive in both key spellings
+      # (symbols are the common Nokogiri idiom); the engines must
+      # resolve both — a symbol-key miss falls through to
+      # prefix-spelling matching and namespaced elements never match.
+      # asciichem's CML group extraction rides exactly this shape.
+      it "resolves symbol-keyed namespace bindings" do
+        doc = ctx.parse(cml_xml)
+        mols = doc.xpath("//cml:molecule", cml: CML_NS)
+        expect(mols.to_a.size).to eq(1)
+
+        groups = mols.first.xpath("./aci:group", aci: ACI_NS)
+        expect(groups.to_a.size).to eq(1)
+        expect(groups.first["multiplicity"]).to eq("2")
+      end
+
+      it "resolves string-keyed namespace bindings identically" do
+        doc = ctx.parse(cml_xml)
+        expect(doc.xpath("//cml:molecule", "cml" => CML_NS).to_a.size).to eq(1)
+      end
+
       # moxml#393: a relative name-test path on the DOCUMENT resolves
       # laxly, descendant-anchored at the root — Nokogiri's own
       # Document#at/#search semantics, now pinned for every adapter.

data/spec/moxml/adapter/leptris_contract_reads_spec.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# leptris-ruby#460 — the Identity contract reads ride the C faces
+# by plain dispatch (NativeNode subclasses inherit the C-defined
+# name/content since binding 1.9.359). The wrapper memo stays; the
+# ADAPTER CROSSING (bind_call through node_name/text_content) goes.
+RSpec.describe "leptris Identity contract reads" do
+  let(:ctx) { Moxml.new(:leptris) }
+
+  before do
+    unless Moxml::Adapter::Leptris::NATIVE_READ_LAYER &&
+        Leptris::XML::NativeNode.method_defined?(:name) &&
+        Leptris::XML::NativeNode.method_defined?(:content)
+      skip "binding #{defined?(Leptris) && Leptris::VERSION} lacks the C contract faces"
+    end
+  end
+
+  def bust(node, *ivars)
+    ivars.each do |iv|
+      node.remove_instance_variable(iv) if node.instance_variable_defined?(iv)
+    end
+  end
+
+  def forbid_crossing!(method)
+    singleton = Moxml::Adapter::Leptris.singleton_class
+    singleton.send(:alias_method, :"#{method}_without_460", method)
+    singleton.send(:define_method, method) { |*| raise "adapter #{method} crossing" }
+    method
+  end
+
+  def restore_crossing!(method)
+    singleton = Moxml::Adapter::Leptris.singleton_class
+    singleton.send(:alias_method, method, :"#{method}_without_460")
+    singleton.send(:remove_method, :"#{method}_without_460")
+  end
+
+  describe "element#name" do
+    it "answers without the adapter node_name crossing" do
+      unless Leptris::XML::NativeNode.method_defined?(:name_read)
+        skip "binding #{Leptris::VERSION} has no name_read face (adapter path is correct there)"
+      end
+      doc = ctx.parse('<root><item id="1">v</item></root>')
+      el = doc.root.children.first
+      expect(el.native).to be_a(Leptris::XML::NativeNode)
+
+      bust(el, :@name)
+      forbid_crossing!(:node_name)
+      begin
+        expect(el.name).to eq("item")
+      ensure
+        restore_crossing!(:node_name)
+      end
+    end
+
+    it "answers the local name for prefixed elements (cross-adapter contract)" do
+      doc = ctx.parse('<root xmlns:ns="urn:u"><ns:p/></root>')
+      el = doc.root.children.first
+      bust(el, :@name)
+      expect(el.name).to eq("p")
+    end
+
+    it "memoizes: warm reads return the same String" do
+      doc = ctx.parse("<root><item/></root>")
+      el = doc.root.children.first
+      first = el.name
+      expect(el.name).to equal(first)
+    end
+
+    it "re-reads after name=" do
+      doc = ctx.parse("<root><item/></root>")
+      el = doc.root.children.first
+      el.name = "renamed"
+      expect(el.name).to eq("renamed")
+    end
+  end
+
+  describe "text#content" do
+    it "answers without the adapter text_content crossing" do
+      unless Leptris::XML::NativeNode.method_defined?(:text_read)
+        skip "binding #{Leptris::VERSION} has no text_read face (adapter path is correct there)"
+      end
+      doc = ctx.parse("<root><item>v</item></root>")
+      tx = doc.root.children.first.children.first
+      expect(tx.native).to be_a(Leptris::XML::NativeNode)
+
+      bust(tx, :@content)
+      forbid_crossing!(:text_content)
+      begin
+        expect(tx.content).to eq("v")
+      ensure
+        restore_crossing!(:text_content)
+      end
+    end
+
+    it "memoizes: warm reads return the same String" do
+      doc = ctx.parse("<root><item>v</item></root>")
+      tx = doc.root.children.first.children.first
+      first = tx.content
+      expect(tx.content).to equal(first)
+    end
+
+    it "re-reads after content=" do
+      doc = ctx.parse("<root><item>v</item></root>")
+      tx = doc.root.children.first.children.first
+      tx.content = "changed"
+      expect(tx.content).to eq("changed")
+    end
+
+    it "restores entities on entity-bearing documents" do
+      ctx2 = Moxml.new(:leptris) { |c| c.restore_entities = true }
+      doc = ctx2.parse("<root><item>a &amp; b</item></root>")
+      tx = doc.root.children.first.children.first
+      bust(tx, :@content)
+      expect(tx.content).to eq("a & b")
+    end
+  end
+
+  describe "the untouched faces" do
+    it "keeps text wrappers named text" do
+      doc = ctx.parse("<root><item>v</item></root>")
+      tx = doc.root.children.first.children.first
+      expect(tx.name).to eq("text")
+    end
+
+    it "keeps element#text on the existing path" do
+      doc = ctx.parse("<root><item>v</item></root>")
+      el = doc.root.children.first
+      expect(el.text).to eq("v")
+    end
+  end
+end

data/spec/moxml/adapter/leptris_detached_text_spec.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Issue #401: Text#content= on a detached (parentless) node answered
+# the engine's bare "Invalid argument" with no indication of the cause.
+# The leptris adapter now re-raises it as a named Moxml error carrying
+# the detachment. Created-unattached nodes work (probe), so only the
+# failing detachment is re-raised.
+RSpec.describe "detached text content= names the cause" do
+  let(:ctx) { Moxml.new(:leptris) }
+
+  it "raises a named Moxml error for a removed text node" do
+    doc = ctx.parse("<r><a>x</a><b>y</b></r>")
+    text = doc.root.children[0].children[0]
+    text.remove
+
+    expect { text.content = "z" }
+      .to raise_error(Moxml::Error, /detached \(parentless\).*issue #401/)
+  end
+
+  it "keeps created-unattached nodes mutable" do
+    text = ctx.create_document.create_text("x")
+    text.content = "y"
+    expect(text.content).to eq("y")
+  end
+
+  it "keeps attached nodes mutable" do
+    doc = ctx.parse("<r><a>x</a></r>")
+    text = doc.root.children[0].children[0]
+    text.content = "z"
+    expect(text.content).to eq("z")
+  end
+end