metanorma-document 0.2.9 → 0.2.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da12347749776b99b68dcc3816de625289ce2e56f51a9716c05d38088a4913b7
-  data.tar.gz: 2bf0989d205c0ab6a0c282fd5c4cab7d0c7deaccf012baafc64fa97c9160029f
+  metadata.gz: d75a3afa9e8f16619cd88b2bf610d81ecd5b6e4d7bc9b507a26c347832d01536
+  data.tar.gz: 2739411b950f3871a28eec551346ee5ded7f643c9f76438574f68d1314fc398b
 SHA512:
-  metadata.gz: 1af9848d0640195e2176378b067214afe02f1da504893ed09686625e0a79f637bfad69fa5575d0959b59d31e78eff2b986dcdb42d63169db853ab808fb52bf22
-  data.tar.gz: 8dd05a2a8ed9344e5d70a35ab3c4653ec9b4c69dc001ef3cd400c6822b4874b8582304df5eee0798f37f8da43388e90fc71dbd88402d41fc1e401cd95fcd396a
+  metadata.gz: 29980c2343686ad9ec1ebb5c582f6483a280c1ff0d7edd5354597ccb5241db71269a01c955ec2c19e215ec2eeaa0675c93563eae33b446926dad6781ed15d2d2
+  data.tar.gz: d6e50bf824ba8f7ea1efabb168743dfd79e3e655547434f9328ba8cea817bce57012f85809940cfd2c9a995784204c846d2964375132978de4cdadebb68efde9

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-21 09:20:40 UTC using RuboCop version 1.86.1.
+# on 2026-07-17 09:09:03 UTC using RuboCop version 1.86.1.
 # 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
@@ -11,16 +11,53 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'metanorma-document.gemspec'
 
-# Offense count: 9
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: with_first_argument, with_fixed_indentation
 Layout/ArgumentAlignment:
   Exclude:
-    - 'lib/metanorma/standard_document.rb'
-    - 'spec/metanorma/flavor_roots/flavor_roots_spec.rb'
+    - 'spec/metanorma/document/components/inline/semantic_content_bug05_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_element, with_fixed_indentation
+Layout/ArrayAlignment:
+  Exclude:
+    - 'spec/metanorma/document/components/inline/span_element_bug01_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'spec/metanorma/document/components/inline/semantic_content_bug05_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'spec/metanorma/document/components/inline/semantic_content_bug05_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: special_inside_parentheses, consistent, align_brackets
+Layout/FirstArrayElementIndentation:
+  Exclude:
+    - 'spec/metanorma/document/components/inline/span_element_bug01_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Exclude:
+    - 'spec/metanorma/document/components/inline/semantic_content_bug05_spec.rb'
 
-# Offense count: 666
+# Offense count: 700
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -29,106 +66,101 @@ Layout/LineLength:
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented, indented_relative_to_receiver
+Layout/MultilineMethodCallIndentation:
   Exclude:
-    - 'lib/metanorma/standard_document.rb'
+    - 'spec/metanorma/document/components/inline/semantic_content_bug05_spec.rb'
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
 Lint/ConstantDefinitionInBlock:
   Exclude:
     - 'spec/metanorma/html/renderer/class_ownership_spec.rb'
+    - 'spec/metanorma/html/renderer/liquid_templates_spec.rb'
 
-# Offense count: 1
+# Offense count: 3
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
     - 'lib/metanorma/html/base_renderer.rb'
+    - 'lib/metanorma/html/renderers/inline_renderer.rb'
+    - 'lib/metanorma/html/standard_renderer.rb'
 
-# Offense count: 3
+# Offense count: 2
 # Configuration parameters: AllowComments, AllowEmptyLambdas.
 Lint/EmptyBlock:
   Exclude:
-    - 'lib/metanorma/html/drops/formula_drop.rb'
     - 'spec/metanorma/iso_document/metadata/title_roundtrip_spec.rb'
 
 # Offense count: 4
 # Configuration parameters: AllowedParentClasses.
 Lint/MissingSuper:
   Exclude:
-    - 'lib/metanorma/html/drops/block_element_drop.rb'
-    - 'lib/metanorma/html/drops/figure_list_entry_drop.rb'
-    - 'lib/metanorma/html/drops/footnote_drop.rb'
-    - 'lib/metanorma/html/drops/toc_entry_drop.rb'
+    - 'lib/metanorma/html/drops/figure_drop.rb'
+    - 'lib/metanorma/html/drops/formula_drop.rb'
+    - 'lib/metanorma/html/drops/sourcecode_drop.rb'
+    - 'lib/metanorma/mirror/id_strategy/positional.rb'
 
 # Offense count: 1
 Lint/StructNewOverride:
   Exclude:
     - 'lib/metanorma/html/component/index_term_collector.rb'
 
-# Offense count: 80
+# Offense count: 23
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
+# NotImplementedExceptions: NotImplementedError
+Lint/UnusedMethodArgument:
+  Exclude:
+    - 'lib/metanorma/mirror/handlers/formula.rb'
+    - 'lib/metanorma/mirror/handlers/sourcecode.rb'
+    - 'lib/metanorma/mirror/output/html_renderers/block_renderers.rb'
+    - 'lib/metanorma/mirror/output/html_renderers/list_renderers.rb'
+    - 'lib/metanorma/mirror/output/html_renderers/section_renderers.rb'
+    - 'lib/metanorma/mirror/output/html_renderers/structural_renderers.rb'
+    - 'lib/metanorma/mirror/output/html_renderers/table_renderers.rb'
+    - 'spec/metanorma/mirror/handler_registry_spec.rb'
+    - 'spec/metanorma/mirror/html_renderer_spec.rb'
+
+# Offense count: 114
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 23
+# Offense count: 11
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 80
+  Max: 47
 
-# Offense count: 1
+# Offense count: 3
 # Configuration parameters: CountBlocks, CountModifierForms.
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 56
+# Offense count: 86
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
-  Exclude:
-    - 'lib/metanorma/document/components/lists/list_item.rb'
-    - 'lib/metanorma/html/base_renderer.rb'
-    - 'lib/metanorma/html/bipm_renderer.rb'
-    - 'lib/metanorma/html/component/index_term_collector.rb'
-    - 'lib/metanorma/html/drops/figure_drop.rb'
-    - 'lib/metanorma/html/drops/formula_drop.rb'
-    - 'lib/metanorma/html/generator.rb'
-    - 'lib/metanorma/html/iso_renderer.rb'
-    - 'lib/metanorma/html/ogc_renderer.rb'
-    - 'lib/metanorma/html/standard_renderer.rb'
-    - 'lib/metanorma/html/theme.rb'
-    - 'lib/metanorma/iso_document/metadata/iso_localized_title.rb'
+  Enabled: false
 
-# Offense count: 101
+# Offense count: 149
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 95
+  Max: 102
 
-# Offense count: 1
+# Offense count: 3
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 7
 
-# Offense count: 51
+# Offense count: 69
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
-  Exclude:
-    - 'lib/metanorma/document/components/lists/list_item.rb'
-    - 'lib/metanorma/html/base_renderer.rb'
-    - 'lib/metanorma/html/bipm_renderer.rb'
-    - 'lib/metanorma/html/component/index_term_collector.rb'
-    - 'lib/metanorma/html/drops/figure_drop.rb'
-    - 'lib/metanorma/html/drops/formula_drop.rb'
-    - 'lib/metanorma/html/generator.rb'
-    - 'lib/metanorma/html/iso_renderer.rb'
-    - 'lib/metanorma/html/ogc_renderer.rb'
-    - 'lib/metanorma/html/standard_renderer.rb'
-    - 'lib/metanorma/html/theme.rb'
-    - 'lib/metanorma/iso_document/metadata/iso_localized_title.rb'
+  Enabled: false
 
-# Offense count: 28
+# Offense count: 52
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
 Naming/MethodParameterName:
@@ -137,23 +169,35 @@ Naming/MethodParameterName:
     - 'lib/metanorma/html/component/footnote_collector.rb'
     - 'lib/metanorma/html/drops/sourcecode_drop.rb'
     - 'lib/metanorma/html/iso_renderer.rb'
+    - 'lib/metanorma/html/renderers/block_renderer.rb'
+    - 'lib/metanorma/html/renderers/inline_renderer.rb'
     - 'spec/metanorma/html/renderer/footnote_collector_spec.rb'
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
 # AllowedMethods: call
 # WaywardPredicates: infinite?, nonzero?
 Naming/PredicateMethod:
   Exclude:
     - 'lib/metanorma/html/base_renderer.rb'
+    - 'lib/metanorma/html/drops/biblio_entry_drop.rb'
+    - 'lib/metanorma/html/renderers/inline_renderer.rb'
 
-# Offense count: 1
+# Offense count: 3
 # Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
 # NamePrefix: is_, has_, have_, does_
 # ForbiddenPrefixes: is_, has_, have_, does_
 # AllowedMethods: is_a?
 # MethodDefinitionMacros: define_method, define_singleton_method
 Naming/PredicatePrefix:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/metanorma/html/base_renderer.rb'
+    - 'lib/metanorma/html/drops/biblio_entry_drop.rb'
+
+# Offense count: 1
+# Configuration parameters: MinSize.
+Performance/CollectionLiteralInLoop:
   Exclude:
     - 'lib/metanorma/html/standard_renderer.rb'
 
@@ -162,30 +206,60 @@ Performance/MapMethodChain:
   Exclude:
     - 'spec/metanorma/flavor_roots/flavor_roots_spec.rb'
 
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: AllowRegexpMatch.
+Performance/RedundantEqualityComparisonBlock:
+  Exclude:
+    - 'spec/metanorma/document/components/inline/fmt_stem_element_bug03_spec.rb'
+
 # Offense count: 7
 RSpec/BeforeAfterAll:
   Exclude:
+    - '**/spec/spec_helper.rb'
+    - '**/spec/rails_helper.rb'
+    - '**/spec/support/**/*.rb'
     - 'spec/metanorma/flavor_roots/flavor_roots_spec.rb'
 
-# Offense count: 18
+# Offense count: 14
+# Configuration parameters: Prefixes, AllowedPatterns.
+# Prefixes: when, with, without
+RSpec/ContextWording:
+  Exclude:
+    - 'spec/metanorma/html/renderer/theme_spec.rb'
+    - 'spec/metanorma/mirror/html_renderer_spec.rb'
+
+# Offense count: 32
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
 
-# Offense count: 95
+# Offense count: 8
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: SkipBlocks, EnforcedStyle, OnlyStaticConstants.
+# SupportedStyles: described_class, explicit
+RSpec/DescribedClass:
+  Exclude:
+    - 'spec/metanorma/document/components/inline/semantic_content_bug05_spec.rb'
+    - 'spec/metanorma/document/components/inline/xref_element_bug04_spec.rb'
+
+# Offense count: 234
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
-  Max: 29
+  Max: 37
 
-# Offense count: 1
+# Offense count: 2
 RSpec/LeakyConstantDeclaration:
   Exclude:
     - 'spec/metanorma/html/renderer/class_ownership_spec.rb'
+    - 'spec/metanorma/html/renderer/liquid_templates_spec.rb'
 
-# Offense count: 2
+# Offense count: 4
 RSpec/MultipleDescribes:
   Exclude:
     - 'spec/metanorma/document_spec.rb'
+    - 'spec/metanorma/mirror/handlers/remaining_handlers_spec.rb'
+    - 'spec/metanorma/mirror/serialization_spec.rb'
     - 'spec/metanorma/standard_document/sections_spec.rb'
 
 # Offense count: 1
@@ -200,30 +274,54 @@ RSpec/NamedSubject:
   Exclude:
     - 'spec/metanorma/flavor_roots/flavor_roots_spec.rb'
 
-# Offense count: 599
+# Offense count: 1061
 # Configuration parameters: AllowedPatterns.
 # AllowedPatterns: ^expect_, ^assert_
 RSpec/NoExpectationExample:
   Enabled: false
 
-# Offense count: 25
+# Offense count: 29
 # Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
 # SupportedInflectors: default, active_support
 RSpec/SpecFilePathFormat:
   Enabled: false
 
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/metanorma/document/components/inline/semantic_content_bug05_spec.rb'
+
 # Offense count: 5
 # This cop supports safe autocorrection (--autocorrect).
 Style/ComparableClamp:
   Exclude:
-    - 'lib/metanorma/html/base_renderer.rb'
     - 'lib/metanorma/html/iso_renderer.rb'
+    - 'lib/metanorma/html/renderers/section_renderer.rb'
     - 'lib/metanorma/html/standard_renderer.rb'
 
 # Offense count: 1
 # This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: literals, strict
-Style/MutableConstant:
+Style/PredicateWithKind:
   Exclude:
-    - 'lib/metanorma/html/base_renderer.rb'
+    - 'spec/metanorma/document/components/inline/fmt_stem_element_bug03_spec.rb'
+
+# Offense count: 2
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/SelectByKind:
+  Exclude:
+    - 'spec/metanorma/document/components/inline/semantic_content_bug05_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArguments:
+  Exclude:
+    - 'spec/metanorma/document/components/inline/semantic_content_bug05_spec.rb'
+    - 'spec/metanorma/document/components/inline/xref_element_bug04_spec.rb'

data/CLAUDE.md

@@ -0,0 +1,26 @@
+# metanorma-document — Project Rules
+
+## ABSOLUTE RULE: NEVER use Nokogiri on document model XML
+
+Document XML (presentation XML) is parsed into lutaml-model objects. All access to document content MUST go through the model object graph — typed attributes, `element_order`, `each_mixed_content`, etc.
+
+NEVER:
+- Call `to_xml` on a model object and then parse that XML with Nokogiri
+- Use Nokogiri to strip, transform, or manipulate document XML content
+- Use Nokogiri CSS selectors on document XML to find elements
+
+The HTML renderer must use the model's typed attributes and the rendering pipeline (`render_paragraph`, `render_mixed_inline`, etc.) to produce HTML. Nokogiri is only acceptable for processing non-document strings (e.g., SVG logo files).
+
+## ABSOLUTE RULE: Use `each_mixed_content` for mixed content nodes
+
+For any node with `mixed? == true`, you MUST use `each_mixed_content` to iterate children. This provides the full sequence of text nodes and elements in correct order.
+
+Do NOT:
+- Use only typed attributes (like `paragraphs`, `title`) for rendering — these only give mapped elements, not text nodes
+- Use `element_order` for inline content — it only shows element children, not interleaved text
+
+`render_ordered_content` uses `element_order` and is acceptable for block-level sections (which contain only element children like paragraphs and lists). But for paragraphs and inline content containers, `each_mixed_content` is mandatory.
+
+## ABSOLUTE RULE: No regex for HTML stripping
+
+Never use regex (`/<[^>]+>/`) to strip HTML tags from rendered output. Text extraction must work directly on model objects via `extract_plain_text` (which walks `element_order` and typed attributes). If you need plain text from a model element, use `extract_plain_text(element)`, not `strip_html(render(element))`.

data/README.adoc

@@ -210,6 +210,150 @@ This library targets the modern Metanorma XML format which uses `<metanorma>` as
 
 Legacy XML formats that use flavor-specific root elements (e.g. `<iso-standard>`, `<m3d-standard>`, `<csa-standard>`, `<un-standard>`) are *not supported*.
 
+== Mirror Format
+
+The `Metanorma::Mirror` module is a ProseMirror-style document model that captures the structural and inline content of a Metanorma document. It serves as an intermediate representation suitable for serialization, round-tripping, alternate rendering pipelines, and editor integrations.
+
+The mirror format is fully model-driven: every node, mark, and document is an instance of a `Model` class. There are no hashes at the API boundary.
+
+=== Model Layer
+
+[horizontal]
+`Model::Container` :: A node with children (`#content`)
+`Model::Leaf` :: A node without children (e.g. `image`, `sourcecode`)
+`Model::Text` :: Inline text carrying a string and a list of `Mark`s
+`Model::SoftBreak` :: A soft line break inside a paragraph
+`Model::Mark` :: An inline decoration (`emphasis`, `strong`, `link`, `xref`, `eref`, `footnote`, `stem`, ...)
+`Model::Guide` :: Output wrapper with `content`, `meta`, and `title`
+`Model::Factory.from_h(hash)` :: Rebuilds a model graph from a serialized hash
+
+Each model class encapsulates its attributes via bounded accessors. `Mark` exposes `[]`, `[]=`, `set_attr`, and `fetch` for safe attribute mutation. `#to_h` is the canonical serialization method.
+
+=== Forward Conversion (Metanorma → Mirror)
+
+[source,ruby]
+require "metanorma/document"
+require "metanorma/mirror"
+
+xml = File.read("spec/fixtures/iso/is/document-en.presentation.xml")
+doc = Metanorma::IsoDocument::Root.from_xml(xml)
+
+transformer = Metanorma::Mirror::Transformer.new
+document = transformer.from_metanorma(doc)
+document.class # => Metanorma::Mirror::Model::Container
+
+=== Reverse Conversion (Mirror → Mirror, with Rewriting)
+
+The `Rewriter` walks a Model graph and produces a new Model graph, applying skip rules and optional per-type customization. (The historical name `MirrorToMetanorma` is no longer accurate: the output is a Model graph, not Metanorma XML. The class was renamed to `Rewriter` to reflect this.)
+
+[source,ruby]
+rewriter = Metanorma::Mirror::Rewriter.new
+rebuilt = rewriter.call(document)
+
+Each `Rewriter` instance seeds its skip set and builder map from class-level defaults at `new` time, so two instances never share state. Instance-level mutation does not leak back to the class, and class-level mutation does not retroactively affect existing instances.
+
+[source,ruby]
+# Instance API — only affects this instance
+rewriter.skip("my_type")
+rewriter.register("my_type") do |node, _rewriter|
+  Metanorma::Mirror::Model::Leaf.new(type: "customized")
+end
+
+# Class API — seeds defaults copied into future instances
+Metanorma::Mirror::Rewriter.skip("always_skip")
+Metanorma::Mirror::Rewriter.register("always_customize") { |n, _r| ... }
+
+Model dispatch is polymorphic: each `Model::*` class implements `accept_rewriter(rewriter)`, which calls the matching `rewriter#rewrite_container` / `#rewrite_leaf` / `#rewrite_text` / `#rewrite_soft_break`. There is no `case/when` on node classes in the dispatch path.
+
+=== Default Handler Registry
+
+`Metanorma::Mirror::DefaultRegistry.build` returns a fresh `HandlerRegistry` pre-populated with the standard Metanorma → Mirror mappings (paragraphs, blocks, lists, sections, terms, structural containers). It is the single source of truth for the default handler set — adding a new model-to-handler mapping is a single `register` call here, with no edits to `HandlerRegistry` itself.
+
+[source,ruby]
+Metanorma::Mirror.build_default_registry
+# => #<Metanorma::Mirror::HandlerRegistry> (fresh instance each call)
+
+=== Metadata Service
+
+`Metanorma::Mirror::Metadata` is a standalone service that extracts document metadata (title, etc.) from a parsed bibdata object. It is consumed by both the forward pipeline (`Output::Pipeline::AttachMetadata`) and the forward transformer (`MetanormaToMirror#extract_root_title`), keeping title-extraction logic in one place rather than duplicated across the Handlers layer.
+
+[source,ruby]
+Metanorma::Mirror::Metadata.title_from_bibdata(doc.bibdata)
+# => "First title string"
+
+=== Serialization
+
+Mirror documents round-trip cleanly through JSON and YAML:
+
+[source,ruby]
+json = Metanorma::Mirror::Serialization::JsonSerializer.serialize(document)
+restored = Metanorma::Mirror::Serialization::JsonSerializer.deserialize(json)
+
+=== ID Strategies
+
+ID assignment is pluggable via `Metanorma::Mirror::IdStrategy`:
+
+[horizontal]
+`IdStrategy::Preserve` :: Default. Keeps element IDs as-is.
+`IdStrategy::Positional` :: Rewrites UUID-style IDs to positional IDs (`sec-X.Y.Z`, `anx-X`, `fig-N`, `table-N`) and translates cross-reference targets.
+
+The `Positional` strategy exposes `register_category(model_class, category)` so new flavors can declare their model classes without editing dispatch code.
+
+=== HTML Rendering from Mirror
+
+`Metanorma::Mirror::Output::HtmlRenderer` produces SSR-ready HTML directly from a mirror Model graph. Renderer behavior is split into pluggable modules registered by node type (`clause`, `paragraph`, `bullet_list`, `table`, ...) and by mark type (`emphasis`, `link`, `xref`, ...). All dispatch is registry-driven (no `case/when` on types), so new node and mark types can be added without modifying core rendering code.
+
+All HTML construction goes through `Nokogiri::HTML4::Builder` (or `Nokogiri::HTML5::Builder` for full documents). String concatenation of HTML is not permitted anywhere in the renderer layer. The `HtmlRenderers` module exposes shared helpers (`build`, `build_fragment`, `embed`, `wrap`, `escape_text`) so each renderer stays declarative.
+
+Node handlers are stored as `UnboundMethod`s bound to the renderer instance at dispatch time. Register a new node handler by passing an instance method reference:
+
+[source,ruby]
+module MyRenderers
+  def self.register(registry)
+    registry.register_node_handler("callout",
+      instance_method(:render_callout))
+  end
+
+  def render_callout(node, depth: 0)
+    HtmlRenderers.build { |doc| doc.span(class: "callout") { doc.text node.attrs["text"] } }
+  end
+end
+MyRenderers.register(Metanorma::Mirror::Output::HtmlRenderer)
+
+Mark handlers are stored as `Proc`s that receive the already-rendered inner HTML and the `Mark` instance:
+
+[source,ruby]
+Metanorma::Mirror::Output::HtmlRenderer.register_mark_handler("kbd",
+  ->(inner_html, _mark) { HtmlRenderers.wrap(:kbd, inner_html) })
+
+=== Output Pipeline
+
+`Metanorma::Mirror::Output::Pipeline` runs the full conversion: parse XML → forward transform → attach metadata. `Metanorma::Mirror::Output::Builder` orchestrates the pipeline and writes through a pluggable `Formats` registry (default: `InlineFormat`).
+
+[source,ruby]
+builder = Metanorma::Mirror::Output::Builder.new(
+  xml_path: "document.presentation.xml",
+  output_path: "output.html",
+  format: :inline,
+  flavor: "iso",
+  id_strategy: Metanorma::Mirror::IdStrategy::Positional.new,
+)
+builder.build
+
+New formats register themselves without editing lookup code:
+
+[source,ruby]
+Metanorma::Mirror::Output::Formats.register(:pdf, MyPdfFormat)
+
+=== CLI
+
+[source,bash]
+# Convert presentation XML to mirror JSON
+metanorma-document to-mirror document.presentation.xml \
+  -o document.mirror.json \
+  --id-strategy positional \
+  --title "My Document"
+
 == Documentation
 
 Detailed architecture documentation is in the `docs/` directory:

data/Rakefile

@@ -9,6 +9,18 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+# Load custom tasks
+Dir.glob("lib/tasks/*.rake").each { |task| load task }
+
+# Build the frontend SPA (frontend/dist/)
+desc "Build frontend SPA assets"
+task :build_frontend do
+  frontend_dir = File.join(__dir__, "frontend")
+  puts "Building frontend..."
+  system("cd #{frontend_dir} && npm install && npm run build") || raise("Frontend build failed")
+end
 
-Dir[File.join(__dir__, "tasks", "*.rake")].each { |f| import f }
+# Hook into bundler's release task to ensure frontend is built
+Rake::Task["release"].enhance(["build_frontend"]) if Rake::Task.task_defined?("release")
+
+task default: %i[spec rubocop]

data/TODO.finalize/01-split-multi-class-files.md

@@ -0,0 +1,8 @@
+# 01 — Split multi-class files into one-class-per-file — DONE
+
+All model files now contain exactly one class per file. Verified: every file under `lib/metanorma/document/`, `lib/metanorma/standard_document/`, `lib/metanorma/iso_document/`, `lib/metanorma/bipm_document/`, `lib/metanorma/itu_document/`, `lib/metanorma/ietf_document/`, `lib/metanorma/cc_document/` is single-class.
+
+Nested classes that are only used internally by their parent (e.g. `AnnotationContainer::Annotation`) are legitimate and NOT split.
+
+## Code quality requirements
+Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/02-remove-data-dist-iso-document-frontend.md

@@ -0,0 +1,6 @@
+# 02 — Remove misplaced `data/dist/iso_document/frontend/` artifacts — DONE
+
+`data/dist/iso_document/frontend/` directory no longer exists. Frontend build artifacts are correctly placed in `frontend/dist/` and included in gemspec via `Dir.glob("frontend/dist/*")`.
+
+## Code quality requirements
+Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/03-align-frontend-iife-and-gha-build.md

@@ -0,0 +1,11 @@
+# 03 — Align frontend IIFE build and GHA gem release with docbook pattern — DONE
+
+Aligned with docbook project:
+- `Rakefile` has `build_frontend` task + release hook
+- `gemspec` includes `frontend/dist/*`
+- `.github/workflows/rake.yml` has `after-setup-ruby: cd frontend && npm install && npm run build`
+- `frontend/vite.config.ts` produces `app.iife.js` + `app.css`
+- `.gitignore` has `frontend/node_modules/` and `frontend/dist/`
+
+## Code quality requirements
+Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/04-theme-per-flavor-config-driven.md

@@ -0,0 +1,9 @@
+# 04 — Data-centric theme system: config files per flavor — DONE
+
+All 13 flavor themes extracted to `data/themes/{flavor}.yaml`. `Theme.load(:iso)` reads YAML and applies overrides. BaseRenderer provides default `Theme.new`. Every flavor renderer uses `Theme.load(:flavor_name)`.
+
+### Remaining enhancement
+Publisher metadata (publishers, publisher_name, logo_map, font_url) still hardcoded in flavor renderers. These should move into theme YAML config so flavor renderers can be auto-generated from config alone.
+
+## Code quality requirements
+Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).

data/TODO.finalize/05-migrate-all-html-to-liquid.md

@@ -0,0 +1,16 @@
+# 05 — Migrate all HTML generation to Liquid templates — DONE
+
+All HTML element generation uses Liquid templates. Zero raw HTML string injection via `@output <<` remains. The `tag()` helper has been removed from `base_renderer.rb`. All remaining `@output <<` calls are text streaming (`escape_html`, whitespace, raw content passthrough) — not HTML element generation.
+
+32+ Liquid templates exist in `lib/metanorma/html/templates/`. The generic `_element.html.liquid` handles most tag wrapping. Specialized templates exist for tables, lists, figures, headings, math, links, etc.
+
+### OOP Liquid pattern
+All rendering uses the `capture_output` + `render_liquid` pattern:
+1. Capture child content into a Ruby string via `capture_output`
+2. Pass captured content to `render_liquid("_template.html.liquid", assigns)`
+3. Result is appended to `@output` by the caller
+
+Drop classes (`Drops::*`) are used for complex objects that need pre-rendered HTML fields (e.g. `BiblioEntryDrop`, `FigureDrop`).
+
+## Code quality requirements
+Ensure code cleanliness and OOP and MECE and fully model-driven, semantically-driven and open/closed principle, DRY, performance. ultrathink. Always think about what can we improve here in architecture and code? Make sure we have good specs throughout. Never use private send methods (breaks encapsulation), instance_variable_set/get, and never use respond_to? (poor typing).