mml 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efbc2e4b8156916d34e524d2f7b6456168f8ef4a0c0c2ade8fbfb2b02bdc2efb
-  data.tar.gz: 8f826d13adfc7f0b556aa5ab6f32f8e8390bf06002a76570845605af7282058a
+  metadata.gz: 2c1d691b0a249ad8e7c35c7eb2daeaa315202df3bd5ce479cca4ff73ef8bd98e
+  data.tar.gz: 1c200909f2749d9b62136a3d23e9a5462454e46e3591587a463114abd7d201f8
 SHA512:
-  metadata.gz: 694df3fcc6b3611d6bac5b5c380b420b91823e697b219ba93a5d9ec22c70d910f8ecef6fef6c419b1acf80660d726259056717380faf8e77d235879b056e3c85
-  data.tar.gz: 72b8f2d1960adec6a3777e43c792cf3d1d3aa4658be47e5bdbf9f7e5cd428ac1dbd3990d7c1685ae4f6ed1a90566b80932046c15424bf4b6a94efa4e39360a29
+  metadata.gz: 6328fec56b6a4bb170ba7085a0a27ae8264d16922119c63e255c72059d442f80ba80bae26179bf8f098ef53a47d25dfd69cacff8056f64f68de95f7219fcfa3f
+  data.tar.gz: c9c9ac8e92274886ea12c9c09d32e899583cbe1b99d753f890465e1ec06822b7b80ad34dd168b246fd0494bdeba588bb8bf8144bdb9ae18ec6c6f6450911a19b

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-31 03:44:08 UTC using RuboCop version 1.86.0.
+# on 2026-04-05 08:05:31 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -16,13 +16,23 @@ Layout/LineLength:
     - 'spec/mml_spec.rb'
     - 'spec/spec_helper.rb'
 
-# Offense count: 1
+# Offense count: 18
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Enabled: false
+
+# Offense count: 5
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 27
+  Max: 172
 
-# Offense count: 3
+# Offense count: 43
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 175
+
+# Offense count: 2
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:

data/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`mml` is a Ruby gem that provides MathML 3 and MathML 4 XML parsing and serialization. It maps MathML elements into Ruby model classes using the `lutaml-model` framework. Part of the [Plurimath](https://github.com/plurimath/mml) ecosystem.
+
+## Commands
+
+```bash
+rake                    # Run specs + rubocop (default task)
+bundle exec rspec       # Run tests
+bundle exec rspec spec/mml_spec.rb:42  # Run single test by line
+bundle exec rspec --only-failures      # Run only previously failing tests
+bundle exec rubocop     # Lint
+bundle exec rubocop -a  # Auto-fix lint issues
+bin/console             # IRB with gem loaded
+```
+
+## Versioned Architecture
+
+**MathML 3 vs MathML 4:** The gem maintains separate class hierarchies for MathML 3 (`Mml::V3::`) and MathML 4 (`Mml::V4::`). Users must reference the versioned namespace explicitly — no backward-compat aliases.
+
+```ruby
+Mml.parse(input)                    # Default: MathML 3
+Mml.parse(input, version: 3)       # Explicit MathML 3
+Mml.parse(input, version: 4)        # MathML 4 with intent/arg attributes
+```
+
+**Directory structure:**
+- `lib/mml/v3/` — MathML 3 element classes (original)
+- `lib/mml/v4/` — MathML 4 element classes (intent/arg added, deprecated attrs removed)
+
+**Key difference:** MathML 4 adds `intent`, `arg`, `displaystyle`, and `scriptlevel` attributes as universal presentation attributes for accessibility markup.
+
+**No hidden delegation:** The `Mml` module does not alias or delegate constants. Use `Mml::V3::Math`, `Mml::V4::Mi`, etc. directly.
+
+## Entry Points
+
+- `Mml.parse(input, version: N)` — parse XML, returns `Mml::V3::Math` or `Mml::V4::Math` object graph
+- `Mml::V3.parse(input)` / `Mml::V4.parse(input)` — version-specific parsing
+- `Mml::V4::Math.from_xml(input)` — directly parse with v4 classes
+- Call `to_xml` on any element to serialize back
+
+## Pattern
+
+Each MathML element is a `Mml::V3::` or `Mml::V4::` class inheriting from `Lutaml::Model::Serializable` with an `xml do...end` DSL block. Two element types:
+- **Leaf elements** (e.g., `Mi`, `Mn`, `Mo`): use `map_content to: :value` for text content
+- **Container elements** (e.g., `Math`, `Mrow`, `Mfrac`): use `mixed_content` to accept arbitrary child elements
+
+**CommonAttributes:** A `no_root` Lutaml model imported into container elements via `import_model`. It dynamically creates `#{tag}_value` attributes for each tag in `Configuration::SUPPORTED_TAGS`. Classes that receive it are listed in `Configuration::COMMON_ATTRIBUTES_CLASSES`.
+
+**Autoloading:** Each version (`lib/mml/v3.rb`, `lib/mml/v4.rb`) autoloads its element classes. `CommonAttributes` is required after all classes exist, then `update_attributes` mixes it into the configured classes.
+
+**Namespace:** Both versions use the same URI (`http://www.w3.org/1998/Math/MathML`) — MathML 4 chose backward compatibility over a new namespace.
+
+## Spec Structure
+
+- `spec/mml_spec.rb` — tests `Mml::V3` and `Mml::V4` with separate fixture directories
+- `spec/fixtures/with_namespace/` — v3 fixtures (MathML 3)
+- `spec/fixtures/with_namespace_prefix/` — v3 fixtures with namespace prefix
+- `spec/fixtures/v4/` — v4 fixtures (MathML 4 with intent attributes)
+
+Specs use the `:nokogiri` Lutaml adapter (configured in `spec_helper.rb`). Runtime uses `:ox` adapter by default.
+
+## Key Dependencies
+
+- `lutaml-model` (~ 0.8.0) — data mapper framework; all element classes inherit from `Lutaml::Model::Serializable`
+- `moxml` — XML parsing library (uses `:ox` adapter by default)
+- `canon` — XML comparison for specs
+
+## Conventions
+
+- `frozen_string_literal: true` in all files
+- RuboCop targets Ruby 3.0; inherits from Ribose OSS guides
+- CI workflows are auto-generated by Cimas — do not edit manually
+- `Gemfile.lock` is gitignored; dependencies come from the gemspec
+- Type signatures exist in `sig/mml.rbs`

data/README.adoc

@@ -39,15 +39,16 @@ $ gem install mml
 ----
 require "mml"
 
-# Parse MathML (defaults to MathML 3)
-math = Mml.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>')
+# Parse MathML with explicit version
+math = Mml.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>', version: 3)
+math4 = Mml.parse(input, version: 4)
 
 # Serialize back to XML
 math.to_xml
-# => "<math xmlns=\"http://www.w3.org/1998/Math/MathML\"><mi>x</mi></math>"
 
-# Parse with explicit version
-math4 = Mml.parse(input, version: 4)
+# Or use versioned modules directly
+Mml::V3.parse(input)
+Mml::V4.parse(input)
 ----
 
 == MathML version architecture
@@ -60,7 +61,7 @@ for backward compatibility.
 ----
                    ┌───────────────────────────────────────────┐
                    │                   Mml                     │
-                   │  (aliases Mml::V3 for backward compat)    │
+                   │  parse() delegates to V3 or V4            │
                    └────────────────────┬──────────────────────┘
                                         │
                     ┌───────────────────┴────────────────────┐
@@ -79,7 +80,7 @@ for backward compatibility.
     │  └────────────┬───────────────┘     │  │  │  + <a> element          │  │
     │               │                     │  │  └────────────┬────────────┘  │
     │  ┌────────────┴────────────┐        │  │  ┌────────────┴────────────┐  │
-    │  │ CommonAttributes        │        │  │  │ CommonAttributes        │  │
+    │  │ CommonElements        │        │  │  │ CommonElements        │  │
     │  │ (child element mixin)   │        │  │  │ (v4 version)            │  │
     │  └─────────────────────────┘        │  |  └─────────────────────────┘  |
     └─────────────────────────────────────┘  └───────────────────────────────┘
@@ -97,7 +98,8 @@ for backward compatibility.
 Mml.parse(input)              # Default: MathML 3 (Mml::V3)
 Mml.parse(input, version: 3)  # Explicit MathML 3
 Mml.parse(input, version: 4)  # MathML 4 with intent/arg attributes
-Mml::V4.parse(input)          # Direct v4 parsing (no default fallback)
+Mml::V3.parse(input)          # Direct v3 parsing
+Mml::V4.parse(input)          # Direct v4 parsing
 ----
 
 === Key differences between MathML 3 and MathML 4
@@ -107,56 +109,79 @@ Mml::V4.parse(input)          # Direct v4 parsing (no default fallback)
 |Feature |MathML 4 additions
 |Universal attributes |`intent`, `arg`, `displaystyle`, `scriptlevel` available on all presentation elements
 |New element |`<a>` hyperlink element with `href`, `hreflang`
-|Deprecated (not serialized) a|
-* `fontfamily`, `fontweight`, `fontstyle`, `fontsize`, `color`, `background` on `mstyle`, `mglyph`, `mspace`
-* `groupalign` on `mtable`, `mtr`, `mlabeledtr`
-* `fence`, `separator` on `mo`
-|Deprecated (recognized but hidden) |`<mlabeledtr>`, `<none>` removed from `CommonAttributes` but classes still exist
+|Deprecated in MathML 4 (still recognized for backward compatibility) a|
+* `fontfamily`, `fontweight`, `fontstyle`, `fontsize`, `color`, `background` on token elements, `mstyle`, `mglyph`, `mspace`
+* `mode`, `macros` on `math`
+* `index` on `mglyph`
+
+See https://github.com/w3c/mathml/issues/5[w3c/mathml#5] and
+https://github.com/w3c/mathml/issues/303[w3c/mathml#303] for details.
 |===
 
-=== Migration from MathML 3 to MathML 4
+=== Migration from previous versions
 
-==== For gem users (upgrading parsing)
+==== require and configuration
 
-If you currently parse MathML and want to use MathML 4 features:
+The `Mml` module no longer aliases versioned constants. Use the explicit version
+namespace:
 
 [source,ruby]
 ----
-# Change this:
-math = Mml.parse(input)
+# Before (no longer supported)
+require "mml/configuration"
+Mml::Configuration.adapter = :nokogiri
+Mml::Configuration.create_context(id: :custom_v3)
+Mml::Math.new(...)
 
-# To this:
-math = Mml.parse(input, version: 4)
+# After — explicit version
+require "mml"
+Mml::V3::Configuration.adapter = :nokogiri
+Mml::V3::Configuration.create_context(
+  id: :custom_v3,
+  substitutions: [
+    { from_type: Mml::V3::Mi, to_type: MyCustomMi }
+  ]
+)
+Mml::V3.parse(input, context: :custom_v3)
+
+# Or for MathML 4
+Mml::V4::Configuration.adapter = :nokogiri
+Mml::V4::Configuration.create_context(
+  id: :custom_v4,
+  substitutions: [
+    { from_type: Mml::V4::Mi, to_type: MyCustomMi }
+  ]
+)
+Mml::V4.parse(input, context: :custom_v4)
 ----
 
-==== For gem users (upgrading serialized output)
+==== Element class references
 
-If you serialize MathML 4 documents and want to ensure compatibility:
+All element classes live under their version namespace:
 
 [source,ruby]
 ----
-# MathML 4 serialization removes deprecated attributes from XML output
-math = Mml.parse(input, version: 4)
-math.to_xml  # No fontfamily, fontweight, color, groupalign, etc. in output
-----
-
-==== For gem extenders (adding custom elements)
+# Before (no longer supported)
+Mml::Mi.new(value: "x")
+Mml::Mrow.new(mi_value: [...])
 
-Custom elements registered via `Configuration.custom_models` are version-specific:
+# After
+Mml::V3::Mi.new(value: "x")
+Mml::V3::Mrow.new(mi_value: [...])
 
-[source,ruby]
-----
-# Register a custom element for MathML 4 only
-Mml::V4::Configuration.custom_models = { Mi => MyCustomMiV4 }
+# Or for MathML 4
+Mml::V4::Mi.new(value: "x", intent: "$x")
+Mml::V4::Mrow.new(mi_value: [...])
 ----
 
-CommonAttributes is version-specific. Elements that exist only in v4 (like `<a>`)
-are automatically handled:
+==== Parsing
+
+`Mml.parse` still works with a `version:` keyword, defaulting to version 3:
 
 [source,ruby]
 ----
-# The <a> element is only in v4 CommonAttributes
-Mml::V4::Mrow.new(a_value: [Mml::V4::A.new(href: "https://...")])
+Mml.parse(input)              # unchanged — defaults to MathML 3
+Mml.parse(input, version: 4)  # use MathML 4
 ----
 
 == Parsing and serialization
@@ -166,13 +191,16 @@ Mml::V4::Mrow.new(a_value: [Mml::V4::A.new(href: "https://...")])
 [source,ruby]
 ----
 # Default namespace
-Mml.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>')
+Mml::V3.parse('<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>')
 
 # Prefixed namespace
-Mml.parse('<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"><mml:mi>x</mml:mi></mml:math>')
+Mml::V3.parse('<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"><mml:mi>x</mml:mi></mml:math>')
 
 # No namespace (namespace injected internally)
-Mml.parse("<math><mi>x</mi></math>", namespace_exist: false)
+Mml::V3.parse("<math><mi>x</mi></math>", namespace_exist: false)
+
+# MathML 4
+Mml::V4.parse(input)
 ----
 
 === Serialization
@@ -217,7 +245,7 @@ math.to_xml
 
 *v4 only*: `a` (hyperlink)
 
-*Deprecated*: `mlabeledtr`, `none` (classes exist but hidden from CommonAttributes in v4)
+*Deprecated*: `mlabeledtr`, `none` (classes exist but hidden from CommonElements in v4)
 
 === Token elements (leaf nodes)
 
@@ -225,13 +253,13 @@ Token elements hold text content in the `value` attribute:
 
 [source,ruby]
 ----
-Mml::Mi.new(value: "x")
-Mml::Mn.new(value: "42")
-Mml::Mo.new(value: "+")
-Mml::Ms.new(value: "text")
-Mml::Mtext.new(value: "label")
-Mml::Mspace.new(width: "1em")
-Mml::Mglyph.new(alt: "symbol")
+Mml::V3::Mi.new(value: "x")
+Mml::V3::Mn.new(value: "42")
+Mml::V3::Mo.new(value: "+")
+Mml::V3::Ms.new(value: "text")
+Mml::V3::Mtext.new(value: "label")
+Mml::V3::Mspace.new(width: "1em")
+Mml::V3::Mglyph.new(alt: "symbol")
 ----
 
 === Container elements
@@ -240,10 +268,11 @@ Container elements hold child elements via `#{tag}_value` collection attributes:
 
 [source,ruby]
 ----
-Mml::Mrow.new(
-  mi_value: [Mml::Mi.new(value: "x")],
-  mo_value: [Mml::Mo.new(value: "+")],
-  mn_value: [Mml::Mn.new(value: "1")],
+Mml::V3::Mrow.new(
+  lutaml_register: Mml::V3::Configuration.context_id,
+  mi_value: [Mml::V3::Mi.new(value: "x")],
+  mo_value: [Mml::V3::Mo.new(value: "+")],
+  mn_value: [Mml::V3::Mn.new(value: "1")],
 )
 # => <mrow><mi>x</mi><mo>+</mo><mn>1</mn></mrow>
 ----
@@ -254,10 +283,12 @@ Build an expression tree by nesting elements:
 
 [source,ruby]
 ----
-Mml::Math.new(
+Mml::V3::Math.new(
+  lutaml_register: Mml::V3::Configuration.context_id,
   mfrac_value: [
-    Mml::Mfrac.new(
-      mi_value: [Mml::Mi.new(value: "a"), Mml::Mi.new(value: "b")],
+    Mml::V3::Mfrac.new(
+      lutaml_register: Mml::V3::Configuration.context_id,
+      mi_value: [Mml::V3::Mi.new(value: "a"), Mml::V3::Mi.new(value: "b")],
     ),
   ],
 )
@@ -268,12 +299,20 @@ Mml::Math.new(
 
 [source,ruby]
 ----
-Mml::Mtable.new(
+Mml::V3::Mtable.new(
+  lutaml_register: Mml::V3::Configuration.context_id,
   mtr_value: [
-    Mml::Mtr.new(
+    Mml::V3::Mtr.new(
+      lutaml_register: Mml::V3::Configuration.context_id,
       mtd_value: [
-        Mml::Mtd.new(mi_value: [Mml::Mi.new(value: "a")]),
-        Mml::Mtd.new(mi_value: [Mml::Mi.new(value: "b")]),
+        Mml::V3::Mtd.new(
+          lutaml_register: Mml::V3::Configuration.context_id,
+          mi_value: [Mml::V3::Mi.new(value: "a")]
+        ),
+        Mml::V3::Mtd.new(
+          lutaml_register: Mml::V3::Configuration.context_id,
+          mi_value: [Mml::V3::Mi.new(value: "b")]
+        ),
       ],
     ),
   ],
@@ -285,6 +324,7 @@ Mml::Mtable.new(
 [source,ruby]
 ----
 Mml::V4::A.new(
+  lutaml_register: Mml::V4::Configuration.context_id,
   href: "https://example.com",
   hreflang: "en",
   mi_value: [Mml::V4::Mi.new(value: "click")]
@@ -292,41 +332,116 @@ Mml::V4::A.new(
 # => <a href="https://example.com" hreflang="en"><mi>click</mi></a>
 ----
 
+== MathML V4 Compliance
+
+This implementation has been audited against the
+https://www.w3.org/TR/MathML4/[MathML 4 W3C Recommendation].
+
+=== Universal V4 Attributes
+
+All MathML 4 presentation elements include `intent`, `arg`, `displaystyle`,
+`scriptlevel`, `mathcolor`, and `mathbackground` via the shared
+`Base::V4Attributes` module.
+
+=== Legacy Schema Support
+
+For backwards compatibility with existing MathML content, this gem supports
+both the strict V4 schema and the legacy schema:
+
+[cols="1,2",options="header"]
+|===
+|Feature |Status
+|Universal V4 attributes (`intent`, `arg`, `displaystyle`, `scriptlevel`) |Full support
+|`mathcolor`, `mathbackground` on all presentation elements |Full support
+|`<a>` hyperlink element |Full support
+|Deprecated font attributes (`fontfamily`, `fontweight`, etc.) |Legacy support (V3 + V4 legacy schema)
+|`fence`, `separator` on `<mo>` |Legacy support (removed from default V4 schema)
+|`none` element |Deprecated in V4 (empty `<mrow>` recommended)
+|`mlabeledtr` element |Legacy support (removed from default V4 schema)
+|===
+
+
 == Internal architecture
 
 === Element class patterns
 
-All element classes inherit from `Lutaml::Model::Serializable`:
+Shared attributes and mappings live in `Base::` modules (`lib/mml/base/`).
+V3 and V4 classes include these modules independently — no cross-version inheritance.
 
-* *Leaf elements*: use `map_content to: :value` for text content
-* *Container elements*: use `mixed_content` for child elements
+* *Leaf elements*: inherit `Lutaml::Model::Serializable`, include `Base::ElementName`
+* *Container elements*: inherit `CommonElements`, include `Base::ElementName`
+
+Each element self-registers in its version's built-in `GlobalContext` context.
 
 [source,ruby]
 ----
-# Leaf — text content
-class Mi < Lutaml::Model::Serializable
-  attribute :value, :string
-  xml do
-    element "mi"
-    map_content to: :value
+# Shared attributes (lib/mml/base/mi.rb)
+module Base::Mi
+  def self.included(klass)
+    klass.class_eval do
+      attribute :value, :string
+      xml do
+        element "mi"
+        map_content to: :value
+      end
+    end
   end
 end
 
-# Container — child elements
-class Mrow < Lutaml::Model::Serializable
-  xml do
-    element "mrow"
-    mixed_content
-  end
+# V3 leaf
+class V3::Mi < Lutaml::Model::Serializable
+  include Base::Mi
+end
+
+# V4 leaf — adds V4-only attributes
+class V4::Mi < Lutaml::Model::Serializable
+  include Base::Mi
+  attribute :intent, :string
 end
+
+# V3 container
+class V3::Mrow < CommonElements
+  include Base::Mrow
+end
+----
+
+=== CommonElements
+
+Container elements inherit `CommonElements`, which defines `#{tag}_value` collection
+attributes for all supported child elements. Attribute types use symbols (e.g., `:mi`,
+`:mfrac`) resolved through `Lutaml::Model::GlobalContext`.
+
+V4's `CommonElements` extends the base with the `<a>` hyperlink element.
+
+=== Context and type resolution
+
+When calling `from_xml` directly (outside of `Mml.parse` or `Mml::V3.parse`), pass
+the version-specific context id for correct type resolution.
+
+NOTE: `lutaml-model` still uses the keyword name `register:` in low-level APIs.
+In MML, the value passed to that keyword should be a context id.
+
+[source,ruby]
+----
+Mml::V3::Math.from_xml(input, register: Mml::V3::Configuration.context_id)
+Mml::V4::Math.from_xml(input, register: Mml::V4::Configuration.context_id)
 ----
 
-=== CommonAttributes
+The `parse` methods handle this automatically.
+
+When constructing container elements directly, also pass the context id on the
+instance via `lutaml_register:` so symbolic child types resolve in the right
+versioned context:
+
+[source,ruby]
+----
+math = Mml::V3::Math.new(
+  lutaml_register: Mml::V3::Configuration.context_id,
+  mi_value: [Mml::V3::Mi.new(value: "x")]
+)
 
-Container elements that accept arbitrary MathML children import `CommonAttributes`,
-which defines `#{tag}_value` collection attributes for all supported child elements.
-The list of classes that receive this mixin is in
-`Configuration::COMMON_ATTRIBUTES_CLASSES`.
+math.to_xml
+----
 
 === Namespace
 
@@ -341,13 +456,41 @@ Three input forms are supported:
 
 [source,ruby]
 ----
-# Switch XML adapter (default: :ox, also supports :nokogiri)
-Mml::Configuration.adapter = :nokogiri
+# Switch XML adapter (default: :ox, :oga on Opal)
+Mml::V3::Configuration.adapter = :nokogiri
+
+# Access the built-in version-specific contexts
+Mml::V3::Configuration.context_id # => :mml_v3
+Mml::V4::Configuration.context_id # => :mml_v4
+Mml::V3::Configuration.context
+Mml::V4::Configuration.context
+
+# Rebuild a built-in context after an explicit GlobalContext.reset!
+Mml::V3::Configuration.populate_context!
+Mml::V4::Configuration.populate_context!
+
+# Create a derived context with substitutions
+Mml::V3::Configuration.create_context(
+  id: :custom_v3,
+  substitutions: [
+    { from_type: Mml::V3::Mi, to_type: MyCustomMi }
+  ]
+)
 
-# Register custom model replacements
-Mml::Configuration.custom_models = { Mi => MyCustomMi }
+# Parse using the custom context
+Mml::V3.parse(input, context: :custom_v3)
+
+# Low-level APIs still use the upstream keyword name `register:`
+Mml::V3::Math.from_xml(input, register: :custom_v3)
 ----
 
+The `context:` keyword is the preferred MML API. The legacy `register:` keyword is
+still accepted temporarily in MML parse methods, but it emits a deprecation warning
+and is normalized to a context id internally.
+
+If you reset global contexts and need the built-in MML contexts restored
+explicitly, call `populate_context!` for the version(s) you want to restore.
+
 == Development
 
 [source,bash]

data/lib/mml/base/deprecated_font_attributes.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mml
+  module Base
+    # Deprecated MathML 1 font attributes: fontfamily, fontweight, fontstyle,
+    # fontsize, color, background.
+    # These are removed in MathML 4 default schema but valid in mathml4-legacy.
+    module DeprecatedFontAttributes
+      def self.included(klass)
+        klass.class_eval do
+          attribute :fontfamily, :string
+          attribute :fontweight, :string
+          attribute :fontstyle, :string
+          attribute :fontsize, :string
+          attribute :color, :string
+          attribute :background, :string
+
+          xml do
+            namespace Mml::Namespace
+            map_attribute "fontfamily", to: :fontfamily
+            map_attribute "fontweight", to: :fontweight
+            map_attribute "fontstyle", to: :fontstyle
+            map_attribute "fontsize", to: :fontsize
+            map_attribute "color", to: :color
+            map_attribute "background", to: :background
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mml/base/maction.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mml
+  module Base
+    module Maction
+      # NOTE: class_eval resolves constants in module's lexical scope.
+      # Use fully qualified names (e.g., Mml::Namespace).
+      def self.included(klass)
+        klass.class_eval do
+          attribute :mathcolor, :string
+          attribute :mathbackground, :string
+          attribute :actiontype, :string
+          attribute :selection, :string
+
+          xml do
+            namespace Mml::Namespace
+            element "maction"
+
+            map_attribute "mathcolor", to: :mathcolor
+            map_attribute "mathbackground", to: :mathbackground
+            map_attribute "actiontype", to: :actiontype
+            map_attribute "selection", to: :selection
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mml/base/maligngroup.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mml
+  module Base
+    module Maligngroup
+      # NOTE: class_eval resolves constants in module's lexical scope.
+      # Use fully qualified names (e.g., Mml::Namespace).
+      def self.included(klass)
+        klass.class_eval do
+          attribute :mathcolor, :string
+          attribute :mathbackground, :string
+          attribute :groupalign, :string
+
+          xml do
+            namespace Mml::Namespace
+            element "maligngroup"
+
+            map_attribute "mathcolor", to: :mathcolor
+            map_attribute "mathbackground", to: :mathbackground
+            map_attribute "groupalign", to: :groupalign
+          end
+        end
+      end
+    end
+  end
+end