metanorma-document 0.2.9 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da12347749776b99b68dcc3816de625289ce2e56f51a9716c05d38088a4913b7
-  data.tar.gz: 2bf0989d205c0ab6a0c282fd5c4cab7d0c7deaccf012baafc64fa97c9160029f
+  metadata.gz: 05125b6d3a480509e630600c04a152707d7af1cf32423a3906b99032fbb18fcd
+  data.tar.gz: 1c45b49ac852306fca98f05fc59cb0f790a5b814a6a3b8b56cfd6960b9cc726c
 SHA512:
-  metadata.gz: 1af9848d0640195e2176378b067214afe02f1da504893ed09686625e0a79f637bfad69fa5575d0959b59d31e78eff2b986dcdb42d63169db853ab808fb52bf22
-  data.tar.gz: 8dd05a2a8ed9344e5d70a35ab3c4653ec9b4c69dc001ef3cd400c6822b4874b8582304df5eee0798f37f8da43388e90fc71dbd88402d41fc1e401cd95fcd396a
+  metadata.gz: 9ebfc36533344fd420cc2286357b77d4fe94213c8f31a0defdd7c4b06af6938e0258472bd279bd275f6a85f34a2c991a4fd12cd90d0b212e5ae9780506353600
+  data.tar.gz: 66b5e24551fd844cb8ad9368a10468509e0b3a7cc15836b5400d57024513da889c76f2571fc0d97cfdfacfacca7e72e6fe8d5d6f92c5bb54bc0a7d57d08d43ad

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-18 16:00:24 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,124 +11,102 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'metanorma-document.gemspec'
 
-# Offense count: 9
-# 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'
-
-# Offense count: 666
+# Offense count: 703
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'lib/metanorma/standard_document.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: 12
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 80
+  Max: 76
 
-# Offense count: 1
+# Offense count: 3
 # Configuration parameters: CountBlocks, CountModifierForms.
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 56
+# Offense count: 84
 # 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: 68
 # 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,17 +115,21 @@ 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_
@@ -155,7 +137,9 @@ Naming/PredicateMethod:
 # MethodDefinitionMacros: define_method, define_singleton_method
 Naming/PredicatePrefix:
   Exclude:
-    - 'lib/metanorma/html/standard_renderer.rb'
+    - 'spec/**/*'
+    - 'lib/metanorma/html/base_renderer.rb'
+    - 'lib/metanorma/html/drops/biblio_entry_drop.rb'
 
 # Offense count: 1
 Performance/MapMethodChain:
@@ -165,27 +149,42 @@ Performance/MapMethodChain:
 # 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: 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: 5
 RSpec/MultipleDescribes:
   Exclude:
     - 'spec/metanorma/document_spec.rb'
+    - 'spec/metanorma/html/flavor_registry_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,13 +199,13 @@ RSpec/NamedSubject:
   Exclude:
     - 'spec/metanorma/flavor_roots/flavor_roots_spec.rb'
 
-# Offense count: 599
+# Offense count: 1076
 # 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:
@@ -216,14 +215,6 @@ RSpec/SpecFilePathFormat:
 # 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:
-  Exclude:
-    - 'lib/metanorma/html/base_renderer.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 (`Transformer#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).

data/TODO.finalize/06-integrate-pubid-library.md

@@ -0,0 +1,16 @@
+# 06 — Integrate pubid library for publication identifier handling — DONE
+
+## What was done
+1. Added `pubid ~> 2.0` to gemspec dependency
+2. Added `gem "pubid", path: "../../mn/pubid"` to Gemfile for local dev
+3. Created `lib/metanorma/html/concerns/pubid_rendering.rb` — `PubidRendering` module with:
+   - `FLAVOR_PUBID_MAP` mapping document class names to pubid modules
+   - `parse_pubid(docidentifier_string)` — flavor-aware pubid parsing
+   - `pubid_to_html(identifier)` — renders to semantic HTML with CSS classes
+   - `resolve_pubid_module` — auto-detects flavor from renderer class
+4. Wired into `BaseRenderer` via `include PubidRendering`
+5. Refactored `render_bibitem_content` in `standard_renderer.rb` to try pubid first
+6. Created specs in `pubid_rendering_spec.rb`
+
+## 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/07-replace-relaton-models-with-relaton-bib.md

@@ -0,0 +1,39 @@
+ # 07 — Integrate relaton-bib library (partially complete)
+
+## Status
+- **Done**: relaton-bib dependency added, 4 models replaced via inheritance, `require` at module level
+- **Blocked**: Most models have incompatible XML schemas (different attribute names/types, different XML mappings)
+
+## What was done
+1. Added `relaton-bib ~> 2.1` to gemspec dependency
+2. Added `require "relaton/bib"` to `lib/metanorma/document/relaton.rb`
+3. Replaced 4 models with inheritance from relaton-bib:
+   - `Phone` < `::Relaton::Bib::Phone` (exact match)
+   - `PriceType` < `::Relaton::Bib::Price` (exact match)
+   - `BibItemLocality` < `::Relaton::Bib::Locality` (exact match)
+   - `Edition` < `::Relaton::Bib::Edition` (inherits + adds `language` attribute)
+
+## Why most models can't be directly replaced
+The 53 relaton models in our project have different XML schemas from relaton-bib's models:
+
+| Difference | Our models | relaton-bib |
+|---|---|---|
+| Attribute names | `on` (BibliographicDate), `bib_locality` (LocalityStack), `validity_begins` (ValidityType) | `at`, `locality`, `begins` |
+| Attribute types | `Components::DataTypes::*` throughout | `LocalizedString`, `LocalizedMarkedUpString` |
+| XML mapping | `map_attribute` for medium, `map_all_content` for logo | `map_element` for medium, `map_element "image"` for logo |
+| Extra attributes | `language` on Edition, `id` on DocumentIdentifier, `stage_abbreviation` on DocumentStatus | Not present |
+| Mixed content | Used in TypedTitleString (em/fn/stem/strong/sub/sup/tt/variant) | Plain content |
+| Model nesting | `CopyrightOwner` wraps `Organization` | `Contributor` as owner |
+
+A full replacement requires updating all 86 consuming references and adapting to relaton-bib's API. This is a separate project-level migration.
+
+## Remaining work for full migration
+1. Update consuming code (86 references) to use relaton-bib attribute names
+2. For models with extra attributes: inherit from relaton-bib and add extras
+3. For models with structural differences: create adapter classes
+4. Remove `lib/metanorma/document/relaton/` once fully migrated
+5. Update autoload configuration
+6. Integration specs for relaton-bib model usage
+
+## 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/08-refactor-renderer-architecture.md

@@ -0,0 +1,25 @@
+# 08 — Refactor renderer architecture for OCP and DRY — DONE
+
+### Completed decomposition (Phase 1)
+BaseRenderer originally included three concern modules:
+- `InlineRendering` (~590 lines, 39 methods)
+- `BlockRendering` (~295 lines, 24 methods)
+- `SectionRendering` (~90 lines, 8 methods)
+
+### Completed composition (Phase 2 — TODO 13)
+Module includes replaced with composition. Each module became a standalone class:
+- `Renderers::InlineRenderer` at `lib/metanorma/html/renderers/inline_renderer.rb`
+- `Renderers::BlockRenderer` at `lib/metanorma/html/renderers/block_renderer.rb`
+- `Renderers::SectionRenderer` at `lib/metanorma/html/renderers/section_renderer.rb`
+- `Renderers::PubidRenderer` at `lib/metanorma/html/renderers/pubid_renderer.rb`
+
+BaseRenderer is now a thin coordinator with delegation wrappers for backward compatibility.
+Old concern modules at `lib/metanorma/html/concerns/` are no longer referenced and can be removed.
+
+### Remaining enhancements
+- Publisher metadata (flavor_publishers, flavor_publisher_name, publisher_logo_map) duplicated across 12+ flavor renderers. See TODO 11 for config-driven migration.
+- Config-driven section ordering. See TODO 14.
+- Theme directories per flavor. See TODO 15.
+
+## 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).