fontisan 0.4.6 → 0.4.7

data/lib/fontisan/stitcher.rb

@@ -1,102 +1,101 @@
 # frozen_string_literal: true
 
 module Fontisan
-  # Multi-source font stitcher. Combines glyphs from one or more
-  # source fonts (UFO or loaded TTF/OTF) into a single new font.
+  # Multi-source font stitcher with explicit subfont declaration.
   #
-  # The Stitcher builds a Fontisan::Ufo::Font from selected glyphs,
-  # then delegates compilation to the existing TtfCompiler or
-  # OtfCompiler. Single source of truth: one compiler pipeline,
-  # whether the input is one UFO or many sources.
+  # Every set of codepoints is explicitly assigned to a named subfont
+  # via the required `into:` keyword. The user controls the collection
+  # structure upfront — there are no defaults and no after-the-fact
+  # splitting.
   #
-  # @example Stitch ASCII from one UFO, Hiragana from another
+  # Single-font output: `write_to` requires a `subfont:` name.
+  # Collection output: `write_collection` writes all declared subfonts.
+  #
+  # @example Single font
   #   stitcher = Fontisan::Stitcher.new
   #   stitcher.add_source(:latin, Fontisan::Ufo::Font.open("latin.ufo"))
-  #   stitcher.add_source(:jp, Fontisan::Ufo::Font.open("jp.ufo"))
-  #   stitcher.include_range(0x41..0x5A, from: :latin)
-  #   stitcher.include_range(0x3040..0x309F, from: :jp)
-  #   stitcher.write_to("stitched.ttf", format: :ttf)
+  #   stitcher.include_range(0x41..0x5A, from: :latin, into: :main)
+  #   stitcher.write_to("out.ttf", format: :ttf, subfont: :main)
+  #
+  # @example Collection
+  #   stitcher = Fontisan::Stitcher.new
+  #   stitcher.add_source(:noto_sans, noto_sans)
+  #   stitcher.add_source(:noto_cjk, noto_cjk)
+  #   stitcher.include_range(0x41..0x5A, from: :noto_sans, into: :latin)
+  #   stitcher.include_range(0x4E00..0x9FFF, from: :noto_cjk, into: :cjk)
+  #   stitcher.write_collection("out.otc", format: :otf2)
   class Stitcher
-    autoload :Source,   "fontisan/stitcher/source"
-    autoload :Selector, "fontisan/stitcher/selector"
+    autoload :Source,          "fontisan/stitcher/source"
+    autoload :Selector,        "fontisan/stitcher/selector"
+    autoload :GlyphSignature,  "fontisan/stitcher/glyph_signature"
+    autoload :Deduplicator,    "fontisan/stitcher/deduplicator"
+    autoload :GlyphLimit,      "fontisan/stitcher/glyph_limit"
 
-    attr_reader :sources, :bindings
+    DEFAULT_DEDUPLICATE = true
 
-    def initialize
+    attr_reader :sources, :subfonts, :info
+
+    def initialize(deduplicate: DEFAULT_DEDUPLICATE)
       @sources = {}
-      @bindings = []
-      @target = Ufo::Font.new
+      @subfonts = Hash.new { |h, k| h[k] = [] }
+      @info = nil
+      @deduplicate = deduplicate
     end
 
-    # Register a named source font.
-    # @param label [Symbol, String] name to reference this source by
-    # @param font [Fontisan::Ufo::Font, Fontisan::SfntFont] the source
     def add_source(label, font)
       @sources[label.to_sym] = Source.new(font)
     end
 
-    # Include all codepoints in a range from a named source.
-    # @param range [Range<Integer>] codepoint range
-    # @param from [Symbol, String] source label
-    def include_range(range, from:)
-      Selector::Range.new(range).apply(source(from), @bindings)
+    def include_range(range, from:, into:)
+      Selector::Range.new(range).apply(source(from), @subfonts[into])
     end
 
-    # Include an explicit list of codepoints.
-    # @param codepoints [Array<Integer>]
-    # @param from [Symbol, String] source label
-    def include_codepoints(codepoints, from:)
-      Selector::Codepoints.new(codepoints).apply(source(from), @bindings)
+    def include_codepoints(codepoints, from:, into:)
+      Selector::Codepoints.new(codepoints).apply(source(from), @subfonts[into])
     end
 
-    # Include a single glyph by donor gid (rare; for unencoded glyphs
-    # like .notdef).
-    # @param donor_gid [Integer]
-    # @param from [Symbol, String] source label
-    def include_gid(donor_gid, from:)
-      Selector::Gid.new(donor_gid).apply(source(from), @bindings)
+    def include_gid(donor_gid, from:, into:)
+      Selector::Gid.new(donor_gid).apply(source(from), @subfonts[into])
     end
 
-    # Always include .notdef from a named source.
-    # @param from [Symbol, String] source label
-    def include_notdef(from:)
-      include_gid(0, from: from)
+    def include_notdef(from:, into:)
+      include_gid(0, from: from, into: into)
     end
 
-    # Set font-wide metadata on the stitched font.
-    # @param info_hash [Hash] any subset of Fontisan::Ufo::Info fields
     def set_info(info_hash)
-      @target.info = Ufo::Info.new(info_hash)
+      @info = Ufo::Info.new(info_hash)
     end
 
-    # Write the stitched font to disk.
-    #
-    # For CBDT/CBLC sources (e.g. NotoColorEmoji), the raw CBDT and
-    # CBLC tables are copied byte-for-byte into the output. This works
-    # because CBDT-mode glyphs are processed first (GIDs 0..N-1),
-    # matching the source's GID layout. Only one CBDT source is
-    # supported; multiple CBDT sources raise MultipleCbdtSourcesError.
-    #
-    # @param path [String] output file path
-    # @param format [Symbol] :ttf or :otf
-    def write_to(path, format: :ttf)
-      build_target_font
+    def subfont_names
+      @subfonts.keys
+    end
+
+    def build_target_font(subfont:)
+      build_target_for(subfont)
+    end
+
+    def write_to(path, format:, subfont:)
+      target = build_target_for(subfont)
+      GlyphLimit.check!(target.glyphs.size, format: format)
+
       compiler = compiler_for(format)
-      compiler_instance = compiler.new(@target)
-      compiler_instance.compile(output_path: path)
+      compiler.new(target).compile(output_path: path)
 
       propagate_cbdt_tables(path) if cbdt_source
-
       path
     end
 
-    # Build the internal UFO::Font from the current bindings. Useful
-    # for testing or for further manipulation before writing.
-    # @return [Fontisan::Ufo::Font]
-    def build_target_font
-      @target = Ufo::Font.new
-      assign_gids_and_copy_glyphs
-      @target
+    def write_collection(path, format:)
+      raise ArgumentError, "no subfonts declared" if @subfonts.empty?
+
+      compiled = @subfonts.keys.map do |name|
+        compile_subfont_to_loaded_font(name, format: format)
+      end
+
+      collection_format = collection_format_for(format)
+      Collection::Builder.new(compiled, format: collection_format,
+                                        optimize: true).build_to_file(path)
+      path
     end
 
     private
@@ -107,9 +106,6 @@ module Fontisan
       end
     end
 
-    # Find the single CBDT source among registered sources, if any.
-    # Raises if more than one CBDT source is present (merge not supported).
-    # @return [Source, nil]
     def cbdt_source
       cbdts = @sources.values.select { |s| s.bitmap_mode == :cbdt }
       if cbdts.size > 1
@@ -120,87 +116,93 @@ module Fontisan
       cbdts.first
     end
 
-    # Copy raw CBDT + CBLC table bytes from the CBDT source into the
-    # compiled output file. The GIDs must match (CBDT glyphs are at
-    # the same GIDs in both source and output because they were added
-    # first during build_target_font).
-    def propagate_cbdt_tables(path)
-      source = cbdt_source
-      return unless source
-
-      compiled = Fontisan::FontLoader.load(path)
-
-      tables = {}
-      compiled.table_names.each do |tag|
-        raw = extract_raw_table(compiled, tag)
-        tables[tag] = raw if raw
-      end
-
-      cbdt_bytes = source.raw_table_bytes("CBDT")
-      cblc_bytes = source.raw_table_bytes("CBLC")
-      tables["CBDT"] = cbdt_bytes if cbdt_bytes
-      tables["CBLC"] = cblc_bytes if cblc_bytes
-
-      sfnt = tables.key?("CFF ") ? 0x4F54544F : 0x00010000
-      Fontisan::FontWriter.write_to_file(tables, path, sfnt_version: sfnt)
-    end
-
-    def extract_raw_table(font, tag)
-      sfnt_table = font.table(tag)
-      return nil unless sfnt_table
-
-      sfnt_table.raw_data
-    rescue StandardError
-      nil
-    end
-
     def compiler_for(format)
       case format.to_sym
       when :ttf then Ufo::Compile::TtfCompiler
       when :otf then Ufo::Compile::OtfCompiler
+      when :otf2 then Ufo::Compile::Otf2Compiler
       else
         raise ArgumentError, "unknown format: #{format.inspect}"
       end
     end
 
-    # Walk bindings in codepoint order, assign sequential new gids,
-    # copy each glyph into the target font's default layer.
-    #
-    # When a CBDT source is present, its glyphs are added FIRST (in
-    # source GID order) so that the CBLC's GID references remain valid.
-    # Glyf-source bindings are processed AFTER, appending new glyphs.
-    def assign_gids_and_copy_glyphs
-      cbdt = cbdt_source
+    def collection_format_for(subfont_format)
+      subfont_format == :ttf ? :ttc : :otc
+    end
+
+    def build_target_for(subfont_name)
+      bindings = @subfonts[subfont_name] || []
+      target = Ufo::Font.new
+      target.info = @info ? @info.dup : Ufo::Info.new
+      dedup = @deduplicate ? Deduplicator.new : nil
+      assign_gids_and_copy_glyphs(bindings, target, dedup)
+      target
+    end
+
+    def compile_subfont_to_loaded_font(subfont_name, format:)
+      target = build_target_for(subfont_name)
+      GlyphLimit.check!(target.glyphs.size, format: format)
+
+      ext = format == :ttf ? ".ttf" : ".otf"
+      Dir.mktmpdir do |dir|
+        sub_path = File.join(dir, "sub#{subfont_name}#{ext}")
+        compiler = compiler_for(format)
+        compiler.new(target).compile(output_path: sub_path)
+        return Fontisan::FontLoader.load(sub_path)
+      end
+    end
+
+    def assign_gids_and_copy_glyphs(bindings, target, deduplicator)
+      cbdt = safe_cbdt_source
 
       if cbdt
-        add_all_cbdt_glyphs(cbdt)
+        add_all_cbdt_glyphs(cbdt, target)
       else
-        add_notdef_from_bindings
+        add_notdef_from(bindings, target, deduplicator)
       end
 
-      sorted_bindings.each do |binding|
+      sorted_bindings(bindings).each do |binding|
         next if binding[:donor_gid].zero?
-
-        # Skip bindings from the CBDT source — its glyphs are already added.
         next if cbdt && binding[:source].equal?(cbdt)
 
         glyph = binding[:source].glyph_for_gid(binding[:donor_gid])
         next unless glyph
 
-        if @target.glyphs.key?(glyph.name)
-          add_extra_unicode(glyph.name, binding[:codepoint])
+        canonical = deduplicator&.find(glyph)
+        if canonical && target.glyphs.key?(canonical)
+          add_extra_unicode(target, canonical, binding[:codepoint])
         else
-          copy_glyph_into(@target, name: glyph.name,
-                                   source: binding[:source],
-                                   donor_gid: binding[:donor_gid],
-                                   codepoint: binding[:codepoint])
+          name = unique_target_name(target, glyph.name)
+          copy_glyph_into(target, name: name, source: binding[:source],
+                                  donor_gid: binding[:donor_gid],
+                                  codepoint: binding[:codepoint])
+          deduplicator&.register(glyph, name)
         end
       end
     end
 
-    # Bindings sorted by codepoint (nil codepoints come last).
-    def sorted_bindings
-      @bindings.sort_by { |b| [b[:codepoint] || Float::INFINITY, b[:donor_gid]] }
+    def safe_cbdt_source
+      cbdts = @sources.values.select { |s| s.bitmap_mode == :cbdt }
+      cbdts.size == 1 ? cbdts.first : nil
+    rescue MultipleCbdtSourcesError
+      nil
+    end
+
+    def sorted_bindings(bindings)
+      bindings.sort_by { |b| [b[:codepoint] || Float::INFINITY, b[:donor_gid]] }
+    end
+
+    def add_notdef_from(bindings, target, deduplicator)
+      notdef_binding = bindings.find { |b| b[:donor_gid].zero? }
+      if notdef_binding
+        copy_glyph_into(target, name: ".notdef",
+                                source: notdef_binding[:source],
+                                donor_gid: 0)
+      else
+        target.layers.default_layer.add(Ufo::Glyph.new(name: ".notdef"))
+      end
+      dedup_target = target.glyphs[".notdef"]
+      deduplicator&.register(dedup_target, ".notdef") if dedup_target
     end
 
     def copy_glyph_into(target_font, name:, source:, donor_gid:, codepoint: nil)
@@ -212,46 +214,85 @@ module Fontisan
       target_font.layers.default_layer.add(copy)
     end
 
-    def add_extra_unicode(glyph_name, codepoint)
+    def add_extra_unicode(target_font, glyph_name, codepoint)
       return unless codepoint
 
-      glyph = @target.glyph(glyph_name)
+      glyph = target_font.glyph(glyph_name)
       glyph.add_unicode(codepoint) unless glyph.unicodes.include?(codepoint)
     end
 
-    # Add .notdef at GID 0 from the first binding that references gid 0.
-    # Falls back to a synthesized empty .notdef if none found.
-    def add_notdef_from_bindings
-      notdef_binding = @bindings.find { |b| b[:donor_gid].zero? }
-      if notdef_binding
-        copy_glyph_into(@target, name: ".notdef",
-                                 source: notdef_binding[:source],
-                                 donor_gid: 0)
-      else
-        @target.layers.default_layer.add(Ufo::Glyph.new(name: ".notdef"))
+    def unique_target_name(target_font, base_name)
+      return base_name unless target_font.glyphs.key?(base_name)
+
+      suffix = 1
+      loop do
+        candidate = "#{base_name}.#{suffix}"
+        return candidate unless target_font.glyphs.key?(candidate)
+
+        suffix += 1
       end
     end
 
-    # Add ALL glyphs from a CBDT source in source GID order. This
-    # ensures the CBLC's GID references remain valid in the output
-    # without rewriting the table. Each glyph gets a placeholder
-    # (no contours) since the bitmap data is in CBDT, not glyf.
-    def add_all_cbdt_glyphs(source)
+    def clone_glyph(original, name:)
+      copy = Ufo::Glyph.new(name: name)
+      copy.width = original.width
+      copy.height = original.height
+      original.contours.each { |c| copy.add_contour(clone_contour(c)) }
+      original.components.each { |c| copy.add_component(c) }
+      original.anchors.each { |a| copy.add_anchor(a) }
+      original.guidelines.each { |g| copy.add_guideline(g) }
+      copy
+    end
+
+    def clone_contour(original)
+      points = original.points.map do |p|
+        Ufo::Point.new(x: p.x, y: p.y, type: p.type, smooth: p.smooth)
+      end
+      Ufo::Contour.new(points)
+    end
+
+    def propagate_cbdt_tables(path)
+      source = cbdt_source
+      return unless source
+
+      compiled = Fontisan::FontLoader.load(path)
+
+      tables = {}
+      compiled.table_names.each do |tag|
+        raw = extract_raw_table(compiled, tag)
+        tables[tag] = raw if raw
+      end
+
+      cbdt_bytes = source.raw_table_bytes("CBDT")
+      cblc_bytes = source.raw_table_bytes("CBLC")
+      tables["CBDT"] = cbdt_bytes if cbdt_bytes
+      tables["CBLC"] = cblc_bytes if cblc_bytes
+
+      sfnt = tables.key?("CFF ") || tables.key?("CFF2") ? 0x4F54544F : 0x00010000
+      Fontisan::FontWriter.write_to_file(tables, path, sfnt_version: sfnt)
+    end
+
+    def extract_raw_table(font, tag)
+      sfnt_table = font.table(tag)
+      return nil unless sfnt_table
+
+      sfnt_table.raw_data
+    rescue StandardError
+      nil
+    end
+
+    def add_all_cbdt_glyphs(source, target)
       ufo = source.font.is_a?(Ufo::Font) ? source.font : nil
       if ufo
-        ufo.glyphs.each_value { |g| @target.layers.default_layer.add(clone_glyph(g, name: g.name)) }
+        ufo.glyphs.each_value { |g| target.layers.default_layer.add(clone_glyph(g, name: g.name)) }
         return
       end
 
-      # For loaded TTF/OTF sources, iterate via cmap to get glyph names.
-      # CBDT fonts (like NotoColorEmoji) may have thousands of glyphs;
-      # we add them all as placeholders.
       maxp = source.font.table("maxp")
       num_glyphs = maxp&.num_glyphs || 0
       cmap = source.font.table("cmap")
       mappings = cmap&.unicode_mappings || {}
 
-      # Build gid → [codepoints] from cmap
       gid_cps = Hash.new { |h, k| h[k] = [] }
       mappings.each { |cp, gid| gid_cps[gid] << cp }
 
@@ -260,28 +301,8 @@ module Fontisan
         glyph = Ufo::Glyph.new(name: name)
         glyph.width = 0
         gid_cps[gid].each { |cp| glyph.add_unicode(cp) }
-        @target.layers.default_layer.add(glyph)
-      end
-    end
-
-    # Deep-copy a glyph with a new name. Used so multiple target
-    # glyphs can share the same source outline without aliasing.
-    def clone_glyph(original, name:)
-      copy = Ufo::Glyph.new(name: name)
-      copy.width = original.width
-      copy.height = original.height
-      original.contours.each { |c| copy.add_contour(clone_contour(c)) }
-      original.components.each { |c| copy.add_component(c) }
-      original.anchors.each { |a| copy.add_anchor(a) }
-      original.guidelines.each { |g| copy.add_guideline(g) }
-      copy
-    end
-
-    def clone_contour(original)
-      points = original.points.map do |p|
-        Ufo::Point.new(x: p.x, y: p.y, type: p.type, smooth: p.smooth)
+        target.layers.default_layer.add(glyph)
       end
-      Ufo::Contour.new(points)
     end
   end
 end

data/lib/fontisan/svg_to_glyf/assembler.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module SvgToGlyf
+    # Orchestrates the full SVG → Ufo::Glyph pipeline:
+    #
+    #   path data + transforms
+    #     → Path::Parser.parse → [Command]
+    #     → Path::ContourBuilder.build → [Ufo::Contour]
+    #     → apply final transform (normalization · group transform)
+    #     → round to Integer
+    #     → Ufo::Glyph
+    #
+    # For SVG files and directories, the Document class extracts the
+    # viewBox, accumulated transforms, and path data; the Assembler
+    # composes the normalizer with the group transform and runs the
+    # pipeline once per path.
+    class Assembler
+      attr_reader :upm
+
+      # @param upm [Integer] font units-per-em
+      def initialize(upm: SvgToGlyf::DEFAULT_UPM)
+        @upm = upm.to_i
+      end
+
+      # Build a glyph directly from a path data string.
+      #
+      # @param path_data [String] SVG path d= attribute
+      # @param codepoint [Integer, nil] Unicode codepoint
+      # @param name [String, nil] glyph name
+      # @param viewbox [Hash{Symbol=>Float}, nil] :width, :height
+      # @param transform [Geometry::AffineTransform, nil] group transform
+      # @return [Fontisan::Ufo::Glyph]
+      def build_from_path_data(path_data, codepoint: nil, name: nil,
+                               viewbox: nil, transform: nil)
+        viewbox ||= { width: @upm, height: @upm }
+        final = normalizer_for(**viewbox).final_transform(transform || Geometry::AffineTransform.identity)
+        contours = build_contours(path_data, final)
+        assemble_glyph(name || glyph_name_for(codepoint), contours, codepoint)
+      end
+
+      # Build a glyph from an SVG file.
+      #
+      # @param file_path [String]
+      # @param codepoint [Integer, nil] override; otherwise derived from filename
+      # @return [Fontisan::Ufo::Glyph]
+      def build_from_file(file_path, codepoint: nil)
+        doc = Document.from_file(file_path)
+        codepoint ||= codepoint_from_filename(File.basename(file_path))
+
+        doc.each_path.with_object(nil) do |(data, transform), _|
+          return build_from_doc_path(data, transform, doc, codepoint)
+        end
+
+        empty_glyph(codepoint)
+      end
+
+      # Build a font from a directory of SVG files.
+      #
+      # @param dir [String]
+      # @return [Fontisan::Ufo::Font]
+      def build_from_directory(dir)
+        font = Fontisan::Ufo::Font.new
+        font.info.units_per_em = @upm
+
+        Dir.glob(File.join(dir, "*.svg")).each do |path|
+          glyph = build_from_file(path)
+          font.glyphs[glyph.name] = glyph
+        end
+
+        font
+      end
+
+      private
+
+      def build_from_doc_path(data, group_transform, doc, codepoint)
+        final = normalizer_for(width: doc.viewbox_width, height: doc.viewbox_height)
+          .final_transform(group_transform)
+        contours = build_contours(data, final)
+        assemble_glyph(glyph_name_for(codepoint), contours, codepoint)
+      end
+
+      def build_contours(path_data, final_transform)
+        commands = Path::Parser.parse(path_data)
+        contours = Path::ContourBuilder.new.build(commands)
+        contours.map { |c| transform_contour(c, final_transform) }
+      end
+
+      def transform_contour(contour, transform)
+        points = contour.points.map do |pt|
+          x, y = transform.apply(pt.x, pt.y)
+          Fontisan::Ufo::Point.new(x: x.round, y: y.round, type: pt.type, smooth: pt.smooth)
+        end
+        Fontisan::Ufo::Contour.new(points)
+      end
+
+      def normalizer_for(width:, height:)
+        Geometry::Normalizer.new(viewbox_width: width, viewbox_height: height, upm: @upm)
+      end
+
+      def assemble_glyph(name, contours, codepoint)
+        glyph = Fontisan::Ufo::Glyph.new(name: name)
+        glyph.width = @upm
+        contours.each { |c| glyph.add_contour(c) }
+        glyph.add_unicode(codepoint) if codepoint
+        glyph
+      end
+
+      def empty_glyph(codepoint)
+        glyph = Fontisan::Ufo::Glyph.new(name: glyph_name_for(codepoint))
+        glyph.width = @upm
+        glyph.add_unicode(codepoint) if codepoint
+        glyph
+      end
+
+      # UFO convention: uniXXXX for BMP, uXXXXX for supplementary planes.
+      def glyph_name_for(codepoint)
+        return "glyph" unless codepoint
+
+        codepoint < 0x10000 ? "uni%04X" % codepoint : "u%05X" % codepoint
+      end
+
+      # Derive a codepoint from a filename like "U+10940.svg" or "10940.svg".
+      def codepoint_from_filename(basename)
+        match = basename.match(/(?:U\+)?([0-9A-Fa-f]{4,6})\.svg\z/)
+        return nil unless match
+
+        match[1].to_i(16)
+      end
+    end
+  end
+end

data/lib/fontisan/svg_to_glyf/document.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Fontisan
+  module SvgToGlyf
+    # Walks an SVG XML document to extract path data and accumulated
+    # transforms. The Document is the single source of truth for which
+    # transforms apply to which paths and what coordinate space the
+    # SVG defines (via viewBox).
+    class Document
+      attr_reader :viewbox_width, :viewbox_height, :source
+
+      # @param xml [String] raw SVG XML
+      def self.from_xml(xml)
+        new(Nokogiri::XML(xml))
+      end
+
+      # @param path [String] file path to an .svg file
+      def self.from_file(path)
+        from_xml(File.read(path))
+      end
+
+      # @param doc [Nokogiri::XML::Document]
+      def initialize(doc)
+        @doc = doc
+        @source = doc
+        extract_viewbox
+      end
+
+      # Yield each <path> element's d= string along with the accumulated
+      # AffineTransform from all ancestor <g> transform= attributes.
+      #
+      # @yieldparam path_data [String] the d= attribute value
+      # @yieldparam transform [Geometry::AffineTransform] accumulated group transform
+      def each_path(&)
+        return enum_for(:each_path) unless block_given?
+
+        walk(@doc.root, Geometry::AffineTransform.identity, &)
+      end
+
+      private
+
+      def extract_viewbox
+        root = @doc.root
+        vb = root&.attribute("viewBox")&.value
+        if vb
+          _, _, w, h = vb.split(/\s+/).map(&:to_f)
+          @viewbox_width = w
+          @viewbox_height = h
+        else
+          @viewbox_width = (root&.attribute("width")&.value || DEFAULT_UPM).to_f
+          @viewbox_height = (root&.attribute("height")&.value || DEFAULT_UPM).to_f
+        end
+      end
+
+      # Recursively walk the XML tree. When a <g> has a transform=,
+      # compose it into the running accumulated transform. When a <path>
+      # is found, yield its d= with the current accumulated transform.
+      def walk(node, accumulated, &)
+        return unless node
+
+        node.children.each do |child|
+          next unless child.element?
+
+          case child.name
+          when "g"
+            child_transform = parse_transform(child)
+            walk(child, accumulated.compose(child_transform), &)
+          when "path"
+            data = child.attribute("d")&.value
+            yield(data, accumulated) if data
+          end
+        end
+      end
+
+      def parse_transform(element)
+        raw = element.attribute("transform")&.value
+        Geometry::TransformParser.parse(raw)
+      end
+    end
+  end
+end