vectory 0.13.1 → 0.13.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f48a547c1520b19d88d77ad41c2e2967da41896163f49ef39492f6f6e73b1af
-  data.tar.gz: cb36e0382b283f7ad50816a5ce5ff5b6a80736a44f8a062db57dd8ce836385f2
+  metadata.gz: 6ee735ec4ea1feac5c918c1255839ae19c9e3468d5f8d9b8137d386ba960eb4f
+  data.tar.gz: a81a2bc24cf8fdcf5804fd1642099aeb4a05e592c52cbe34265ee99d4d2b77e6
 SHA512:
-  metadata.gz: 11759d94c1a88218d39f5e4561a661c1c0bee4f371d9c369571d95c34e141dadfb308646c890fc08ddef5a5484fe381e5303b07fc153985b0989fd249e85d8c8
-  data.tar.gz: 1a0151957b311956558f7935e548e92d2678d283238eb66445ec7203916b3fba3753f93140affb5145b732df6f8cd3b75746a2985f9801875a2bf4688f021ad3
+  metadata.gz: ad9305a8070f277be8cfa9f60e2237e46937995490a3c031df57f115fc3151f07fac9c3fd1e74254b9266fe0dda4fbae864eddc32fac68cd6999307cc2f0142f
+  data.tar.gz: cc73b481d8e550a4d05a010945c3051fa6d8fe91b40689a777c3247b25c1c5be1abe0e4b500fc78012f99a51ef2614347908949638512726705e60cbcc5f4df6

data/.github/workflows/rake.yml

@@ -9,7 +9,7 @@ on:
   pull_request:
 
 permissions:
-  contents: write
+  contents: read
   packages: read
 
 jobs:
@@ -20,5 +20,29 @@ jobs:
       submodules: true
       choco-cache: true
       private-fonts: false
+      cascade: false
     secrets:
       pat_token: ${{ secrets.CLARICLE_CI_PAT_TOKEN }}
+
+  tests-passed:
+    needs: rake
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Tests passed
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.CLARICLE_CI_PAT_TOKEN || github.token }}
+          repository: ${{ github.repository }}
+          event-type: tests-passed
+          client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}", "type": "tests-passed"}'
+
+      - if: startsWith(github.ref, 'refs/tags/v')
+        name: Repository ready for release
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.CLARICLE_CI_PAT_TOKEN || github.token }}
+          repository: ${{ github.repository }}
+          event-type: do-release
+          client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}", "type": "do-release"}'

data/README.adoc

@@ -410,6 +410,39 @@ gem bump --version minor --tag --push
 ----
 
 
+== Serialized SVG transforms
+
+Vectory exposes immutable transformations of serialized XML strings. Class
+selectors are parsed with Crass (`~> 1.0`, `>= 1.0.7`); class lists and selectors
+use the same positional `_inject_<index>` suffix as ID disambiguation.
+`SvgClassSuffixer` is the canonical Vectory class-suffix implementation.
+
+[source,ruby]
+----
+cleanup = Vectory::SvgTransform.disambiguate(index: 0, duplicate_ids: collisions) >>
+  Vectory::SvgTransform.suffix_classes(index: 0) >>
+  Vectory::SvgTransform.bind_namespaces(bind: { "xlink" => "http://www.w3.org/1999/xlink" })
+result = cleanup.call(svg_xml)
+----
+
+The executable profiles are `graft` (`G`), `svg_cleanup` (`D -> S -> N`),
+and `graft_then_svg_cleanup` (`G -> D -> S -> N`). Other sequences are rejected;
+construction prefixes cannot execute until complete. Cleanup accepts a selected
+SVG root, while a graft can accept a complete host document. Reapplying a profile
+with the same captured inputs is XML-equivalent. Step options are deeply frozen
+snapshots, so later changes to a caller's collision map cannot change a pipeline.
+
+Namespace binding preserves expanded element and attribute names; it is separate
+from the legacy `SvgDocument#namespace` ID/link cleanup. See the API reference for
+safe binding, unbinding and URI-to-prefix remapping.
+
+For multiple embedded SVGs, graft the complete mapped document once, then build a
+fresh cleanup pipeline for each SVG from the current collision map. Merge each
+result's IDs before constructing the next pipeline. Standoc #1298 adopts ID
+disambiguation while retaining its inline Crass helpers; adopting
+`SvgClassSuffixer` is a separate downstream task after a containing release.
+SVG-to-PNG rendering is a separate projection feature.
+
 == Contributing
 
 Bug reports and pull requests are welcome on GitHub at:

data/docs/Gemfile

@@ -3,6 +3,9 @@ source "https://rubygems.org"
 # Jekyll plugins
 gem "jekyll", "~> 3.0"
 gem "just-the-docs", "~> 0.7"
+# Jekyll 3 dependencies require these gems explicitly on recent Ruby versions.
+gem "base64", "~> 0.2"
+gem "bigdecimal", ">= 3.1", "< 5"
 
 # Markdown and AsciiDoc processing
 gem "asciidoctor", "~> 2.0"

data/docs/lychee.toml

@@ -6,20 +6,11 @@ exclude = [
   'http://localhost:*',
   'http://127.0.0.1:*',
   'file:///*',
-]
-
-# Exclude mailto: links
-exclude = [
+  # Exclude mailto: links
   'mailto:*',
-]
-
-# Exclude version-specific URLs that may break
-exclude = [
+  # Exclude version-specific URLs that may break
   'https://github.com/*/releases/tag/*',  # GitHub release tags
   'https://rubygems.org/gems/*/versions/*',  # RubyGem version history
-]
-
-# Allow certain redirects
-exclude = [
+  # Example domains used in docs
   'https://example.com/*',  # Example domains used in docs
 ]

data/docs/reference/api.adoc

@@ -430,6 +430,90 @@ fig1_ISO_17301-1_2016 → fig1_ISO_17301-1_2016_000000000
 * **ID suffix** (`id_suffix` parameter): Derived from document/container identity. Optional.
 * **Index suffix** (`index_suffix` parameter): Zero-padded position (0, 1, 2... → _000000000, _000000001). Automatically applied.
 
+== Serialized SVG transforms
+
+All methods consume XML strings and return a new XML string. The input DOM is
+never shared with the result. These content transforms do not render PNG images.
+
+* `SvgClassSuffixer.rewrite(content, suffix)` updates XML class lists and CSS class
+  selectors using Crass, including escaped identifiers and nested selector rules.
+  Reapplying the same suffix is idempotent.
+* `SvgNamespaceBinding.rewrite(content, bind: {}, unbind: [], remap: {})` binds
+  prefix-to-URI declarations, unbinds unused prefixes, and remaps URIs to target
+  prefixes. An empty or nil prefix means the default namespace. Expanded names
+  are preserved; default namespaces never qualify unprefixed attributes.
+  Conflicting bindings, used unbinds and identity-changing default remaps raise
+  `ArgumentError`. Malformed, rootless or non-SVG input also raises `ArgumentError`.
+* `SvgSubtreeGraft.replace_root_content(host_content, processed_content)` preserves
+  the host document/root metadata and replaces only the ordered root children,
+  including text, comments, CDATA and processing instructions. Invalid input
+  raises `Vectory::ParsingError`, identifying `host_content` or `processed_content`.
+  Grafts decode each input's XML encoding and return UTF-8, updating an existing
+  encoding declaration while preserving document content and envelope order.
+
+`SvgTransform` factories return named immutable steps:
+
+* `graft_into(host_content:)` validates and captures the host at construction.
+* `disambiguate(index:, duplicate_ids:)` delegates to `SvgIdDisambiguator` with a
+  deeply copied collision map and `_inject_<index>` suffix.
+* `suffix_classes(index:)` uses that same suffix for classes.
+* `bind_namespaces(bind: {}, unbind: [], remap: {})` uses the namespace contract above.
+
+Compose steps with `>>`. `SvgTransformPipeline#steps` exposes stable names and
+deeply frozen option snapshots; `#profile` identifies the executable profile.
+`#call(content)` returns serialized XML. Exactly three profiles can execute:
+
+[cols="1,1,2",options="header"]
+|===
+|Profile |Steps |Scope
+|`graft` |`G` |A complete rooted processed document grafted into the captured host.
+|`svg_cleanup` |`D -> S -> N` |Exactly one selected SVG root, including its nested SVGs.
+|`graft_then_svg_cleanup` |`G -> D -> S -> N` |A captured host whose root is SVG.
+|===
+
+Appending an invalid sequence raises `ArgumentError` containing
+`invalid step sequence`. Calling an incomplete prefix raises `ArgumentError`
+containing `incomplete profile`. A wrong input scope raises `ArgumentError`
+containing `execution-scope mismatch`. Parse errors stop execution and propagate.
+
+=== Standoc migration boundary
+
+Map and graft the complete prepared host once, then process the selected SVGs in
+document order. Preserve the caller's sequential collision map; do not use the
+batch `SvgIdDisambiguator.duplicate_ids` helper for this compatibility flow.
+
+[source,ruby]
+----
+mapped = Vectory::SvgMapping.new(original_host).call.to_xml
+grafted = Vectory::SvgTransform.graft_into(host_content: original_host).call(mapped)
+document = Leptris::XML.parse(grafted)
+collisions = {}
+document.xpath("//*[local-name()='svg' and not(ancestor::*[local-name()='svg'])]").each_with_index do |svg, index|
+  # Make inherited namespace bindings explicit before serializing this subtree.
+  declared_prefixes = svg.namespace_definitions.map(&:prefix)
+  svg.namespaces.each do |name, uri|
+    prefix = name == "xmlns" ? nil : name.delete_prefix("xmlns:")
+    next if declared_prefixes.include?(prefix)
+
+    svg.add_namespace_definition(prefix, uri)
+  end
+  pipeline = Vectory::SvgTransform.disambiguate(index: index, duplicate_ids: collisions) >>
+    Vectory::SvgTransform.suffix_classes(index: index) >>
+    Vectory::SvgTransform.bind_namespaces(bind: { "xlink" => "http://www.w3.org/1999/xlink" })
+  cleaned = pipeline.call(svg.to_xml)
+  Leptris::XML.parse(cleaned).xpath("//*[@id]").each { |node| collisions[node["id"]] = true }
+  svg.replace(cleaned)
+end
+----
+
+Each pipeline retains the collision map as it existed at construction. The first
+repeated root ID remains unchanged; the later one receives its positional suffix.
+The selected SVG must carry its in-scope namespace declarations across the string
+boundary; a declaration inherited from the host is otherwise lost by `to_xml`.
+Standoc #1298 consumes `SvgIdDisambiguator` and retains its current Crass helpers.
+`SvgClassSuffixer` is the canonical Vectory implementation; later adoption and
+removal of the inline helpers require a separate task after a containing release.
+
 == See Also
 
 * link:../guides/error-handling/[Error Handling Guide] - Common errors and solutions

data/lib/vectory/svg_class_suffixer.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "crass"
+require "leptris"
+
+module Vectory
+  # Suffixes SVG class lists and CSS class selectors without normalizing CSS.
+  class SvgClassSuffixer
+    RULE_AT_RULES = %w[media supports layer container document -moz-document
+                       scope starting-style keyframes -webkit-keyframes].freeze
+    SELECTOR_FUNCTIONS = %w[is where not has nth-child nth-last-child host
+                            host-context slotted].freeze
+    private_constant :RULE_AT_RULES, :SELECTOR_FUNCTIONS
+
+    class << self
+      # @param content [String] SVG XML, or a host document containing SVGs
+      # @param suffix [String] a CSS identifier suffix, e.g. "_inject_0"
+      # @return [String] rewritten XML
+      def rewrite(content, suffix)
+        doc = parse(content)
+        doc.xpath("//*[local-name()='svg']").each do |svg|
+          ([svg] + svg.xpath(".//*")).each do |element|
+            rewrite_element(element, suffix)
+          end
+        end
+        doc.to_xml
+      end
+
+      private
+
+      def parse(content)
+        doc = Leptris::XML.parse(content)
+        # Recent Leptris versions recover malformed XML by default.
+        raise Leptris::XML::ParseError, doc.errors.first.message if doc.respond_to?(:errors) && !doc.errors.empty?
+
+        doc
+      end
+
+      def rewrite_element(element, suffix)
+        rewrite_classes(element, suffix)
+        return unless element.name == "style"
+
+        rewrite_style(element, suffix)
+      end
+
+      def rewrite_style(element, suffix)
+        # Parse the complete CSS stream, even when an XML comment or CDATA
+        # boundary splits a token. Apply insertions to the original text nodes
+        # so comments, processing instructions and CDATA remain in place.
+        nodes = element.xpath(".//text()")
+        changes = css_insertions(nodes.map(&:text).join, suffix)
+        offset = 0
+        nodes.each do |node|
+          text = node.text
+          rewrite_style_node(node, text, offset, changes)
+          offset += text.length
+        end
+      end
+
+      def rewrite_style_node(node, text, offset, changes)
+        rewritten = text.dup
+        changes.each do |position, insertion|
+          next unless position > offset && position <= offset + text.length
+
+          rewritten.insert(position - offset, insertion)
+        end
+        node.content = rewritten unless rewritten == text
+      end
+
+      def rewrite_classes(element, suffix)
+        # Keep attribute reads and writes on Leptris's native attribute layer.
+        attribute = element.attribute_nodes.find { |node| node.name == "class" }
+        if attribute
+          attribute.value = attribute.value.gsub(/[^\t\n\f\r ]+/) do |name|
+            name.end_with?(suffix) ? name : "#{name}#{suffix}"
+          end
+        end
+      end
+
+      def css_insertions(css, suffix)
+        changes = {}
+        rules = Crass::Parser.new(css, preserve_comments: true).consume_rules(top_level: true)
+        rewrite_rules(rules, suffix, changes)
+        # Crass tolerates malformed CSS but stringify may repair or drop it.
+        # Token positions use CSS-normalized newlines; map them to the source.
+        offsets = source_offsets(css)
+        changes.sort.reverse.map { |position, insertion| [offsets[position], insertion] }
+      end
+
+      def source_offsets(css)
+        offsets = [0]
+        css.scan(/\r\n|./m) { |character| offsets << (offsets.last + character.length) }
+        offsets
+      end
+
+      def rewrite_rules(rules, suffix, changes)
+        rules.each do |rule|
+          case rule[:node]
+          when :qualified_rule
+            rewrite_selector(rule[:prelude], suffix, changes)
+            rewrite_nested_rules(rule[:block], suffix, changes)
+          when :at_rule
+            rewrite_at_rule(rule, suffix, changes)
+          end
+        end
+      end
+
+      def rewrite_nested_rules(tokens, suffix, changes)
+        # Crass's declaration parser predates CSS nesting and discards nested
+        # rules. Walk its component values, keeping declaration values opaque.
+        parser = Crass::Parser.new(tokens)
+        prelude = []
+        while (token = parser.tokens.consume)
+          case token[:node]
+          when :semicolon
+            prelude.clear
+          when :at_keyword
+            rewrite_nested_at_rule(parser, prelude, suffix, changes)
+          when :simple_block
+            rewrite_nested_block(token, prelude, suffix, changes)
+          else
+            prelude << token
+          end
+        end
+      end
+
+      def rewrite_nested_at_rule(parser, prelude, suffix, changes)
+        if prelude.all? { |token| trivia?(token) }
+          parser.tokens.reconsume
+          rewrite_at_rule(parser.consume_at_rule, suffix, changes)
+          prelude.clear
+        else
+          prelude << parser.tokens.current
+        end
+      end
+
+      def rewrite_nested_block(token, prelude, suffix, changes)
+        if token[:start] == "{" && !custom_property?(prelude)
+          rewrite_selector(prelude, suffix, changes)
+          rewrite_nested_rules(token[:value], suffix, changes)
+          prelude.clear
+        else
+          prelude << token
+        end
+      end
+
+      def trivia?(token)
+        [:comment, :whitespace].include?(token[:node])
+      end
+
+      def custom_property?(tokens)
+        significant = tokens.reject { |token| trivia?(token) }
+        significant.first&.dig(:node) == :ident && significant.first[:value].start_with?("--") &&
+          significant[1]&.dig(:node) == :colon
+      end
+
+      def rewrite_at_rule(rule, suffix, changes)
+        return unless rule[:block] && RULE_AT_RULES.include?(rule[:name].downcase)
+
+        rewrite_scope(rule[:prelude], suffix, changes) if rule[:name].downcase == "scope"
+        rewrite_nested_rules(rule[:block], suffix, changes)
+      end
+
+      def rewrite_scope(tokens, suffix, changes)
+        tokens.each do |token|
+          next unless token[:node] == :simple_block && token[:start] == "("
+
+          rewrite_selector(token[:value], suffix, changes)
+        end
+      end
+
+      def rewrite_selector(tokens, suffix, changes)
+        previous = nil
+        tokens.each do |token|
+          next if token[:node] == :comment
+
+          if class_identifier?(token, previous)
+            suffix_identifier(token, suffix, changes)
+          elsif selector_function?(token)
+            rewrite_selector(token[:value], suffix, changes)
+          end
+          previous = token
+        end
+      end
+
+      def class_identifier?(token, previous)
+        token[:node] == :ident && previous&.dig(:node) == :delim && previous[:value] == "."
+      end
+
+      def selector_function?(token)
+        token[:node] == :function && SELECTOR_FUNCTIONS.include?(token[:name].downcase)
+      end
+
+      def suffix_identifier(token, suffix, changes)
+        return if token[:value].end_with?(suffix)
+
+        # A trailing short hex escape can absorb the first suffix character.
+        # Add its optional terminator only when concatenation changes meaning.
+        combined = Crass::Tokenizer.tokenize(token[:raw] + suffix).first
+        insertion = combined[:value] == token[:value] + suffix ? suffix : " #{suffix}"
+        changes[token[:pos] + token[:raw].length] = insertion
+      end
+    end
+  end
+end

data/lib/vectory/svg_id_disambiguator.rb

@@ -0,0 +1,138 @@
+require "leptris"
+
+module Vectory
+  # Disambiguates element ids across multiple SVG documents embedded in one
+  # output (the multi-svg collision problem): ids that appear in more than
+  # one SVG get a per-document suffix, and every reference form is rewritten
+  # to match — `url(#id)` in presentation attributes and `<style>` blocks,
+  # `href`/`xlink:href` fragment references, and the `id` attributes
+  # themselves.
+  #
+  # This is the string-in/string-out counterpart of SvgMapping's document
+  # processing: content in, processed content out, same as SvgMapping's
+  # "serialize on entry" contract. Ported from metanorma-standoc's
+  # svg_uniqueids cleanup (lib/metanorma/cleanup/image.rb), where it was
+  # written against Nokogiri inline.
+  #
+  # Usage — N embedded SVGs, disambiguate by position:
+  #
+  #   dupes = Vectory::SvgIdDisambiguator.duplicate_ids(svgs)
+  #   svgs.map.with_index { |svg, i| Vectory::SvgIdDisambiguator.rewrite(svg, "_inject_#{i}", dupes) }
+  #
+  class SvgIdDisambiguator
+    # SVG elements whose ids are referenced through presentation attributes
+    # and CSS rather than href: the tag maps to the attributes that carry
+    # the reference (nil = the tag name itself is the CSS property).
+    IRI_TAG_PROPERTIES_MAP = {
+      "clipPath" => ["clip-path"],
+      "color-profile" => nil,
+      "cursor" => nil,
+      "filter" => nil,
+      "linearGradient" => ["fill", "stroke"],
+      "marker" => ["marker", "marker-end", "marker-mid", "marker-start"],
+      "mask" => nil,
+      "pattern" => ["fill", "stroke"],
+      "radialGradient" => ["fill", "stroke"],
+    }.freeze
+
+    URL_RE = %r{url\("?#([a-zA-Z][\w:.-]*)"?\)}.freeze
+    private_constant :URL_RE
+
+    class << self
+      # Ids that appear more than once across the given SVG contents.
+      #
+      # @param contents [Array<String>] SVG document contents
+      # @return [Hash{String => Integer}] id => occurrence count (count >= 2)
+      def duplicate_ids(contents)
+        contents.flat_map { |c| id_values(Leptris::XML.parse(c)) }
+          .group_by(&:itself).transform_values(&:count)
+          .delete_if { |_, v| v < 2 }
+      end
+
+      # Suffix every id in +duplicate_ids+ with +suffix+ inside +content+,
+      # rewriting all reference forms to match. Ids absent from the map are
+      # left untouched.
+      #
+      # @param content [String] SVG document content
+      # @param suffix [String] the full disambiguator, separator included
+      #   (e.g. "_inject_0")
+      # @param duplicate_ids [Hash{String => Integer}] from .duplicate_ids
+      # @return [String] the rewritten content
+      def rewrite(content, suffix, duplicate_ids)
+        doc = Leptris::XML.parse(content)
+        svg_roots(doc).each { |svg| rewrite_svg(svg, suffix, duplicate_ids) }
+        doc.to_xml
+      end
+
+      private
+
+      def svg_roots(doc)
+        root = doc.root
+        if root&.name == "svg"
+          [root]
+        else
+          # SVGs embedded in a host document
+          doc.xpath("//*[local-name()='svg']")
+        end
+      end
+
+      def id_values(doc)
+        doc.xpath("//*").filter_map { |e| e["id"] if e["id"] }
+      end
+
+      def rewrite_svg(svg, suffix, ids)
+        id_elems = svg.xpath(".//*[@id]")
+        id_elems = [svg] + id_elems if svg["id"]
+        iri_properties = iri_properties(id_elems)
+        ([svg] + svg.xpath("//*")).each { |e| rewrite_element(e, iri_properties, suffix, ids) }
+      end
+
+      def rewrite_element(elem, iri_properties, suffix, ids)
+        if elem.name == "style"
+          elem.children = rewrite_urls(elem.text, suffix, ids)
+          return
+        end
+
+        # All attribute reads AND writes go through attribute_nodes: mixing
+        # in the elem[...] accessors after an id write desyncs the native
+        # attribute layer (leptris-ruby#526).
+        nodes = elem.attribute_nodes || []
+        return if nodes.empty?
+
+        iri_properties.each do |p|
+          node = nodes.find { |a| a.name == p } or next
+          node.value = rewrite_urls(node.value, suffix, ids)
+        end
+        nodes.each do |a|
+          case a.name
+          when "id"
+            a.value = "#{a.value}#{suffix}" if ids[a.value]
+          when "xlink:href", "href"
+            v = a.value.to_s.strip
+            a.value = "#{a.value}#{suffix}" if v.start_with?("#") && ids[v.sub(/\A#/, "")]
+          end
+        end
+      end
+
+      # The CSS-referenceable properties present among the id-bearing
+      # elements, plus "style" when any exist (standoc svg_iri_properties).
+      def iri_properties(id_elems)
+        iri_tag_names = id_elems.filter_map do |e|
+          e.name if IRI_TAG_PROPERTIES_MAP.key?(e.name)
+        end.uniq
+        iri_properties = iri_tag_names.flat_map do |t|
+          IRI_TAG_PROPERTIES_MAP[t] || [t]
+        end.uniq
+        return [] if iri_properties.empty?
+
+        iri_properties + ["style"]
+      end
+
+      def rewrite_urls(text, suffix, ids)
+        text.gsub(URL_RE) do |x|
+          ids[$1] ? "url(##{$1}#{suffix})" : x
+        end
+      end
+    end
+  end
+end

data/lib/vectory/svg_namespace_binding.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "leptris"
+
+module Vectory
+  # Declaration changes on one serialized SVG. Remaps use namespace URIs,
+  # rather than lexical source prefixes, so shadows and repeats are unambiguous.
+  # Existing aliases remain unless explicitly requested in +unbind+.
+  class SvgNamespaceBinding
+    def self.rewrite(content, bind: {}, unbind: [], remap: {})
+      new(content, bind, unbind, remap).rewrite
+    end
+
+    def initialize(content, bind, unbind, remap)
+      unless bind.is_a?(Hash) && unbind.is_a?(Array) && remap.is_a?(Hash)
+        raise ArgumentError, "invalid namespace request: expected maps and an array"
+      end
+
+      normalize_options(bind, unbind, remap)
+      @document = parse(content)
+      @elements = @document.xpath("//*")
+      validate_names
+    end
+
+    def rewrite
+      targets = requested_targets
+      targets.each { |prefix, uri| preflight_target(prefix, uri) }
+      preflight_unbind
+      targets.each { |prefix, uri| bind_target(prefix, uri) }
+      @elements.each { |element| remap_element(element) }
+      unbind_namespaces
+      @document.to_xml
+    end
+
+    private
+
+    def normalize_options(bind, unbind, remap)
+      @bind = normalize_bindings(bind)
+      @unbind = unbind.map { |prefix| normalize_prefix(prefix) }.uniq
+      @remap = remap.to_h { |uri, prefix| [validate_uri(uri), normalize_prefix(prefix)] }
+    end
+
+    def normalize_bindings(bind)
+      bindings = {}
+      bind.each do |prefix, uri|
+        prefix = normalize_prefix(prefix)
+        uri = validate_uri(uri)
+        add_target(bindings, prefix, uri)
+      end
+      bindings
+    end
+
+    def requested_targets
+      targets = @bind.dup
+      @remap.each { |uri, prefix| add_target(targets, prefix, uri) }
+      targets
+    end
+
+    def add_target(targets, prefix, uri)
+      if targets.key?(prefix) && targets[prefix] != uri
+        raise ArgumentError, "namespace conflict: incompatible requested bindings"
+      end
+
+      targets[prefix] = uri
+    end
+
+    def bind_target(prefix, uri)
+      @document.root.add_namespace_definition(prefix, uri) unless
+        @document.root.namespaces[declaration_name(prefix)] == uri
+    end
+
+    def unbind_element(element)
+      element.namespace_definitions.each do |namespace|
+        element.remove_namespace_definition(namespace.prefix) if @unbind.include?(namespace.prefix)
+      end
+    end
+
+    def unbind_namespaces
+      # Descendants still need their inherited source bindings during remapping.
+      @elements.each { |element| unbind_element(element) }
+    end
+
+    def normalize_prefix(prefix)
+      return nil if prefix.nil? || prefix == ""
+      if !prefix.is_a?(String) || !/\A[A-Za-z_][A-Za-z0-9_.-]*\z/.match?(prefix) ||
+          prefix.downcase.start_with?("xml")
+        raise ArgumentError, "invalid namespace request: invalid or reserved prefix"
+      end
+
+      prefix
+    end
+
+    def validate_uri(uri)
+      unless uri.is_a?(String) && !uri.empty? && !/\s/.match?(uri) &&
+          !["http://www.w3.org/XML/1998/namespace", "http://www.w3.org/2000/xmlns/"].include?(uri)
+        raise ArgumentError, "invalid namespace request: expected nonempty namespace URI"
+      end
+
+      uri
+    end
+
+    def parse(content)
+      raise ArgumentError, "invalid SVG: expected serialized string" unless content.is_a?(String)
+
+      document = Leptris::XML.parse(content, strict: true)
+      unless document.root&.name == "svg"
+        raise ArgumentError, "invalid SVG: expected SVG root"
+      end
+
+      document
+    rescue Leptris::XML::Error => e
+      raise ArgumentError, "invalid SVG: #{e.message}"
+    end
+
+    def declaration_name(prefix)
+      prefix ? "xmlns:#{prefix}" : "xmlns"
+    end
+
+    def validate_names
+      @elements.each do |element|
+        if element.name.include?(":") && !element.namespace&.href
+          raise ArgumentError, "invalid SVG: unbound element prefix"
+        end
+
+        validate_attributes(element)
+      end
+    end
+
+    def validate_attributes(element)
+      element.attribute_nodes.each do |attr|
+        if attr.name.include?(":") && !attr.namespace_uri
+          raise ArgumentError, "invalid SVG: unbound attribute prefix"
+        end
+      end
+    end
+
+    def preflight_target(prefix, uri)
+      preflight_declarations(prefix, uri)
+      preflight_default(uri) unless prefix
+    end
+
+    def preflight_declarations(prefix, uri)
+      @elements.each do |element|
+        element.namespace_definitions.each do |namespace|
+          if namespace.prefix == prefix && namespace.href != uri
+            raise ArgumentError, "namespace conflict: target prefix already bound"
+          end
+        end
+      end
+    end
+
+    def preflight_default(uri)
+      if @elements.any? { |element| !element.namespace&.href }
+        raise ArgumentError, "default namespace: would qualify unqualified elements"
+      end
+      return unless remapped_to_default?(uri)
+      return unless attributes_use_uri?(uri)
+
+      raise ArgumentError, "default namespace: attributes require an explicit prefix"
+    end
+
+    def remapped_to_default?(uri)
+      @remap[uri].nil? && @remap.key?(uri)
+    end
+
+    def attributes_use_uri?(uri)
+      @elements.any? { |element| element.attribute_nodes.any? { |attr| attr.namespace_uri == uri } }
+    end
+
+    def preflight_unbind
+      @unbind.each do |prefix|
+        if @bind.key?(prefix) || @remap.value?(prefix)
+          raise ArgumentError, "namespace conflict: target also requested for unbind"
+        end
+
+        preflight_prefix_usage(prefix)
+      end
+    end
+
+    def preflight_prefix_usage(prefix)
+      @elements.each do |element|
+        used = element_uses_prefix?(element, prefix) || attributes_use_prefix?(element, prefix)
+        raise ArgumentError, "namespace in use: cannot remove requested prefix" if used
+      end
+    end
+
+    def element_uses_prefix?(element, prefix)
+      namespace = element.namespace
+      namespace && namespace.prefix == prefix && !@remap.key?(namespace.href)
+    end
+
+    def attributes_use_prefix?(element, prefix)
+      element.attribute_nodes.any? do |attr|
+        attr.namespace_uri && attr.name.split(":")[0...-1].join(":") == prefix &&
+          !@remap.key?(attr.namespace_uri)
+      end
+    end
+
+    def remap_element(element)
+      # Snapshot before changing names: native namespace resolution is lexical.
+      namespace = element.namespace
+      attributes = attribute_snapshot(element)
+      if namespace && @remap.key?(namespace.href)
+        element.name = qualified_name(@remap[namespace.href], element.name)
+      end
+      remap_attributes(element, attributes)
+    end
+
+    def attribute_snapshot(element)
+      element.attribute_nodes.map do |attr|
+        [attr, attr.namespace_uri, attr.name.split(":").last, attr.value]
+      end
+    end
+
+    def remap_attributes(element, attributes)
+      attributes.each do |attr, uri, local, value|
+        next unless @remap.key?(uri)
+
+        attr.remove
+        element[qualified_name(@remap[uri], local)] = value
+      end
+    end
+
+    def qualified_name(prefix, local)
+      prefix ? "#{prefix}:#{local}" : local
+    end
+  end
+end

data/lib/vectory/svg_subtree_graft.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "leptris"
+
+module Vectory
+  # Replaces serialized root content while retaining the host document envelope.
+  class SvgSubtreeGraft
+    ENCODING_SIGNATURES = {
+      "\x00\x00\xFE\xFF".b => "UTF-32", "\xFF\xFE\x00\x00".b => "UTF-32",
+      "\xFE\xFF".b => "UTF-16", "\xFF\xFE".b => "UTF-16",
+      "\x00\x00\x00<".b => "UTF-32BE", "<\x00\x00\x00".b => "UTF-32LE",
+      "\x00<\x00?".b => "UTF-16BE", "<\x00?\x00".b => "UTF-16LE"
+    }.freeze
+    private_constant :ENCODING_SIGNATURES
+
+    class << self
+      # @return [String] the complete host document with processed root children
+      def replace_root_content(host_content, processed_content)
+        host_content = utf8_content(host_content, "host_content")
+        processed_content = utf8_content(processed_content, "processed_content")
+        host = parse_document(host_content, "host_content")
+        processed = parse_document(processed_content, "processed_content")
+        # Native node copying/adoption can drop interleaved namespaced attributes.
+        # Reparse serialized children instead of crossing that copy boundary.
+        children = processed.root.children.map { |node| serialize_child(node, host.root.namespaces) }
+        host.root.children = children
+        serialize_host(host, host_content)
+      end
+
+      # @api private
+      # Leptris consumes UTF-8 bytes without decoding XML encoding declarations.
+      # Normalize a working copy; captured pipeline options retain the original.
+      def utf8_content(content, label)
+        encoding = source_encoding(content)
+        utf8 = content.dup.force_encoding(encoding).encode(Encoding::UTF_8)
+        return utf8 if Encoding.find(encoding) == Encoding::UTF_8
+
+        utf8.sub(/\A(<\?xml[ \t\r\n][^?]*\bencoding\s*=\s*)(["'])[^"']+\2/) do
+          "#{Regexp.last_match(1)}#{Regexp.last_match(2)}UTF-8#{Regexp.last_match(2)}"
+        end
+      rescue EncodingError, ArgumentError => e
+        raise ParsingError, "invalid #{label} XML: #{e.message}"
+      end
+
+      private
+
+      def source_encoding(content)
+        bytes = content.b
+        signature = ENCODING_SIGNATURES.find { |prefix, _| bytes.start_with?(prefix) }
+        return signature.last if signature
+
+        bytes[/\A(?:\xEF\xBB\xBF)?<\?xml[ \t\r\n][^?]*\bencoding\s*=\s*(["'])([^"']+)\1/n, 2] || "UTF-8"
+      end
+
+      def serialize_host(host, content)
+        # The document serializer moves DOCTYPE before leading comments/PIs.
+        # Keep the original envelope and serialize only the retained host root.
+        prefix = content.byteslice(0, host.root.byte_offset)
+        suffix = content[/(?:[ \t\r\n]|<!--(?:(?!-->).)*-->|<\?(?:(?!\?>).)*\?>)*\z/m]
+        "#{prefix}#{host.root.to_xml}#{suffix}"
+      end
+
+      def parse_document(content, label)
+        document = Leptris::XML.parse(content, strict: true)
+        raise ParsingError, "#{label} has no document root" unless document.root
+
+        document
+      rescue Leptris::XML::ParseError => e
+        # Strict parsing also rejects valid rootless XML. Appending a root
+        # validates that envelope without allowing repaired malformed input.
+        begin
+          Leptris::XML.parse("#{content}<vectory-root-check/>", strict: true)
+        rescue Leptris::XML::ParseError
+          raise ParsingError, "invalid #{label} XML: #{e.message}"
+        end
+        raise ParsingError, "#{label} has no document root"
+      end
+
+      def serialize_child(node, host_namespaces)
+        seal_namespaces(node, host_namespaces) if node.element?
+        node.to_xml
+      end
+
+      def seal_namespaces(node, host_namespaces)
+        # Retain inherited bindings only where the host cannot supply them.
+        namespaces = { "xmlns" => "" }.merge(node.namespaces)
+        declared = node.namespace_definitions.map(&:prefix)
+        namespaces.each do |name, uri|
+          prefix = name == "xmlns" ? nil : name.delete_prefix("xmlns:")
+          next if declared.include?(prefix) || host_namespaces[name] == uri
+
+          node.add_namespace_definition(prefix, uri)
+        end
+      end
+    end
+  end
+end

data/lib/vectory/svg_transform.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "leptris"
+
+module Vectory
+  # An immutable, named operation at a serialized XML boundary.
+  class SvgTransform
+    attr_reader :name, :options
+
+    class << self
+      def graft_into(host_content:)
+        host = host_content.dup.freeze
+        root = Leptris::XML.parse(SvgSubtreeGraft.utf8_content(host, "host_content"), strict: true).root
+        raise ParsingError, "host_content has no document root" unless root
+
+        new(:graft_into, { host_content: host, svg_host: root.name == "svg" })
+      rescue Leptris::XML::SyntaxError, Leptris::XML::ParseError => e
+        raise ParsingError, "invalid host_content XML: #{e.message}"
+      end
+
+      def disambiguate(index:, duplicate_ids:)
+        new(:disambiguate, { index: index, duplicate_ids: duplicate_ids })
+      end
+
+      def suffix_classes(index:)
+        new(:suffix_classes, { index: index })
+      end
+
+      def bind_namespaces(bind: {}, unbind: [], remap: {})
+        new(:bind_namespaces, { bind: bind, unbind: unbind, remap: remap })
+      end
+
+      private
+
+      def snapshot(value)
+        case value
+        when Hash
+          value.to_h { |key, item| [snapshot(key), snapshot(item)] }.freeze
+        when Array
+          value.map { |item| snapshot(item) }.freeze
+        else
+          value.frozen? ? value : value.dup.freeze
+        end
+      end
+    end
+
+    def initialize(name, options)
+      @name = name
+      @options = self.class.send(:snapshot, options)
+      freeze
+    end
+    private_class_method :new
+
+    def >>(other)
+      SvgTransformPipeline.new([self]) >> other
+    end
+
+    def call(content)
+      SvgTransformPipeline.new([self]).call(content)
+    end
+
+    # Pipeline execution owns ordering and scope checks.
+    def apply(content)
+      case name
+      when :graft_into
+        SvgSubtreeGraft.replace_root_content(options.fetch(:host_content), content)
+      when :disambiguate
+        SvgIdDisambiguator.rewrite(content, suffix, options.fetch(:duplicate_ids))
+      when :suffix_classes
+        SvgClassSuffixer.rewrite(content, suffix)
+      when :bind_namespaces
+        SvgNamespaceBinding.rewrite(content, **options)
+      end
+    end
+
+    private
+
+    def suffix
+      "_inject_#{options.fetch(:index)}"
+    end
+  end
+end

data/lib/vectory/svg_transform_pipeline.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "leptris"
+
+module Vectory
+  # Only the supported whole-document and selected-SVG profiles are executable.
+  class SvgTransformPipeline
+    PROFILES = {
+      graft: %i[graft_into],
+      svg_cleanup: %i[disambiguate suffix_classes bind_namespaces],
+      graft_then_svg_cleanup: %i[graft_into disambiguate suffix_classes bind_namespaces],
+    }.transform_values(&:freeze).freeze
+
+    attr_reader :steps
+
+    def initialize(steps)
+      unless steps.all?(SvgTransform)
+        raise ArgumentError, "invalid step sequence: expected SVG transforms"
+      end
+
+      @steps = steps.dup.freeze
+      validate_sequence
+      freeze
+    end
+
+    def >>(other)
+      additions = other.is_a?(SvgTransformPipeline) ? other.steps : [other]
+      self.class.new(steps + additions)
+    end
+
+    def profile
+      PROFILES.key(steps.map(&:name))
+    end
+
+    def call(content)
+      raise ArgumentError, "incomplete profile: #{steps.map(&:name).join(' -> ')}" unless profile
+
+      validate_scope(content)
+      output = steps.reduce(content) { |xml, step| step.apply(xml) }
+      profile == :graft_then_svg_cleanup ? finalize_graft(output) : output
+    end
+
+    private
+
+    def finalize_graft(output)
+      # Cleanup serializers may reorder the envelope. Keep the cleaned root,
+      # including its new attributes and bindings, inside the captured envelope.
+      host_content = SvgSubtreeGraft.utf8_content(steps.first.options.fetch(:host_content), "host_content")
+      host = Leptris::XML.parse(host_content, strict: true)
+      prefix = host_content.byteslice(0, host.root.byte_offset)
+      tail = host_content[/(?:[ \t\r\n]|<!--(?:(?!-->).)*-->|<\?(?:(?!\?>).)*\?>)*\z/m]
+      "#{prefix}#{final_graft_root(output).to_xml}#{tail}"
+    end
+
+    def final_graft_root(output)
+      root = Leptris::XML.parse(output, strict: true).root
+      # Bindings sealed onto grafted children may now be supplied by the root.
+      root.xpath(".//*").each { |element| remove_redundant_namespaces(element) }
+      root
+    end
+
+    def remove_redundant_namespaces(element)
+      inherited = element.parent.namespaces
+      element.namespace_definitions.each do |namespace|
+        name = namespace.prefix ? "xmlns:#{namespace.prefix}" : "xmlns"
+        element.remove_namespace_definition(namespace.prefix) if inherited[name] == namespace.href
+      end
+    end
+
+    def validate_sequence
+      names = steps.map(&:name)
+      unless !names.empty? && PROFILES.values.any? { |profile| profile.take(names.length) == names }
+        raise ArgumentError, "invalid step sequence: #{names.join(' -> ')}"
+      end
+    end
+
+    def validate_scope(content)
+      case profile
+      when :svg_cleanup
+        validate_svg_root(content)
+      when :graft_then_svg_cleanup
+        return if steps.first.options.fetch(:svg_host)
+
+        raise ArgumentError, "execution-scope mismatch: graft_then_svg_cleanup requires an SVG host root"
+      end
+    rescue Leptris::XML::SyntaxError, Leptris::XML::ParseError => e
+      raise ParsingError, "invalid content XML: #{e.message}"
+    end
+
+    def validate_svg_root(content)
+      root = Leptris::XML.parse(content, strict: true).root
+      return if root&.name == "svg"
+
+      raise ArgumentError, "execution-scope mismatch: svg_cleanup requires an SVG root"
+    end
+  end
+end

data/lib/vectory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vectory
-  VERSION = "0.13.1"
+  VERSION = "0.13.3"
 end

data/lib/vectory.rb

@@ -15,13 +15,11 @@ module Vectory
   class NotWrittenToDiskError < Error; end
 
   class ParsingError < Error; end
-end
 
-require_relative "vectory/errors"
-require_relative "vectory/version"
+  require_relative "vectory/errors"
+  require_relative "vectory/version"
 
-# Lazy load: all other internal Vectory dependencies via autoload
-module Vectory
+  # Lazy load: all other internal Vectory dependencies via autoload
   # Core utilities
   autoload :Utils, "vectory/utils"
 
@@ -37,11 +35,15 @@ module Vectory
   autoload :Svg, "vectory/svg"
   autoload :SvgMapping, "vectory/svg_mapping"
   autoload :SvgDocument, "vectory/svg_document"
+  autoload :SvgIdDisambiguator, "vectory/svg_id_disambiguator"
+  autoload :SvgClassSuffixer, "vectory/svg_class_suffixer"
+  autoload :SvgNamespaceBinding, "vectory/svg_namespace_binding"
+  autoload :SvgSubtreeGraft, "vectory/svg_subtree_graft"
+  autoload :SvgTransform, "vectory/svg_transform"
+  autoload :SvgTransformPipeline, "vectory/svg_transform_pipeline"
   autoload :FileMagic, "vectory/file_magic"
-end
 
-# Define additional module methods
-module Vectory
+  # Define additional module methods
   def self.ui
     @ui ||= Logger.new($stdout).tap do |logger|
       logger.level = ENV["VECTORY_LOG"] || Logger::WARN

data/vectory.gemspec

@@ -16,21 +16,22 @@ Gem::Specification.new do |spec|
 
   spec.homepage      = "https://github.com/metanorma/vectory"
   spec.license       = "BSD-2-Clause"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.bindir        = "exe"
   spec.executables   = ["vectory"]
   spec.require_paths = ["lib"]
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(bin|spec)/})
+    f.match(%r{^(bin|spec|TODO\.[^/]+)/})
   end
-  spec.test_files = `git ls-files -- {spec}/*`.split("\n")
   spec.required_ruby_version = ">= 3.1.0"
 
   spec.add_dependency "base64"
+  spec.add_dependency "crass", "~> 1.0", ">= 1.0.7"
   spec.add_dependency "emfsvg", "~> 0.1", ">= 0.1.2"
   spec.add_dependency "image_size", ">= 3.2.0"
+  spec.add_dependency "leptris", "~> 1.9.399"
   spec.add_dependency "marcel", "~> 1.0"
-  spec.add_dependency "leptris", ">= 1.9.361.1"
   spec.add_dependency "postsvg", "~> 0.3"
   spec.add_dependency "thor", "~> 1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vectory
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.13.3
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -24,6 +24,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: crass
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.7
 - !ruby/object:Gem::Dependency
   name: emfsvg
   requirement: !ruby/object:Gem::Requirement
@@ -59,33 +79,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 3.2.0
 - !ruby/object:Gem::Dependency
-  name: marcel
+  name: leptris
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 1.9.399
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 1.9.399
 - !ruby/object:Gem::Dependency
-  name: leptris
+  name: marcel
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.9.361.1
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.9.361.1
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: postsvg
   requirement: !ruby/object:Gem::Requirement
@@ -167,8 +187,14 @@ files:
 - lib/vectory/image_resize.rb
 - lib/vectory/ps.rb
 - lib/vectory/svg.rb
+- lib/vectory/svg_class_suffixer.rb
 - lib/vectory/svg_document.rb
+- lib/vectory/svg_id_disambiguator.rb
 - lib/vectory/svg_mapping.rb
+- lib/vectory/svg_namespace_binding.rb
+- lib/vectory/svg_subtree_graft.rb
+- lib/vectory/svg_transform.rb
+- lib/vectory/svg_transform_pipeline.rb
 - lib/vectory/utils.rb
 - lib/vectory/vector.rb
 - lib/vectory/version.rb
@@ -178,7 +204,8 @@ files:
 homepage: https://github.com/metanorma/vectory
 licenses:
 - BSD-2-Clause
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: