ucode 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d21572adc317e05b3a29573cf799cc8cedd61c56949339d844022c9ccf92b0e
-  data.tar.gz: 41ff686beb95370ff0927002fc0cc9350aa448221b8dbf12c87712d005059e98
+  metadata.gz: ebf9b5b2d2f0443697ac2cfe6f19ad8c5e1af310943ae4332eadc2df56e68c48
+  data.tar.gz: 2f14bc10e5d5012e4b17cd544443c59e1feadef979bec2144f11dbf53e14c32f
 SHA512:
-  metadata.gz: 2de58e0bab78c0be15ef4e99ab699333198702012832985958eb86910c0151f47b4147b07f958c2ba881d9f9750d7336586151a264ad835339a54064412907e6
-  data.tar.gz: f3a90c63779e0eec7d93fd221063f80cf8d64df16707185a3f9c201abf8d2e1376ece32a0da2af1b5513d0190fdb0a785b5dbcccf65fbb427ff31ae745c22ca7
+  metadata.gz: f2db668d6889a95d79ecaff540791d438044d2f9d066198b6255b6586d1f09b1433cf9d359ffa65e8b803e28c61b579bd9d08e3cfb35014ac3f49b0a0a48d351
+  data.tar.gz: 96a98950b3cfdca7fe6301647a997c9ca9fc96960a5af99ca934ca7e0066d19d7fd8c463910d50bb24f4b956e98f572cec9ef83dc30abbd03466baf1248c748b

data/config/unicode17_universal_glyph_set.yml

@@ -1,6 +1,6 @@
 ---
 unicode_version: 17.0.0
-ucode_version: 0.3.2
+ucode_version: 0.3.3
 generated_at: '2026-06-28T00:00:00Z'
 default_sources:
 - kind: fontist

data/lib/ucode/code_chart/extractor.rb

@@ -30,7 +30,8 @@ module Ucode
     # not checked out.
     class Extractor
       # Result of extracting one codepoint.
-      Result = Struct.new(:codepoint, :svg, :tier, :provenance, keyword_init: true)
+      Result = Struct.new(:codepoint, :svg, :tier, :provenance,
+                          keyword_init: true)
 
       # @param block [Ucode::Models::Block] block whose assigned
       #   codepoints will be extracted
@@ -100,10 +101,13 @@ module Ucode
       end
 
       def embedded_pillar_sources
-        embedded_source = Glyphs::EmbeddedFonts::PdfLocation.new(
+        embedded_source = Glyphs::EmbeddedFonts::PdfSource.new(
           pdf: @pdf_path, cache_dir: @cache_dir,
         )
-        catalog = Glyphs::EmbeddedFonts::Catalog.new(embedded_source)
+        catalog = Glyphs::EmbeddedFonts::Catalog.new(
+          embedded_source,
+          block_range: (@block.range_first..@block.range_last),
+        )
         renderer = Glyphs::EmbeddedFonts::Renderer.new(catalog)
         [Glyphs::Sources::Pillar1EmbeddedTounicode.new(renderer: renderer)]
       end

data/lib/ucode/code_chart/writer.rb

@@ -47,7 +47,7 @@ module Ucode
       # @param ucd_version [String, nil] UCD version to stamp on
       #   provenance. nil = resolved via {VersionResolver.resolve(nil)}.
       # @param cache_dir [Pathname, String, nil] font-stream cache
-      #   directory for the EmbeddedFonts::PdfLocation.
+      #   directory for the EmbeddedFonts::PdfSource.
       # @param now [Time, nil] timestamp override (for tests).
       # @param pillar3_source, tier1_sources: forwarded to the Extractor.
       def initialize(output_root:, pdf_path:, ucd_version: nil,

data/lib/ucode/error.rb

@@ -110,6 +110,11 @@ module Ucode
   # `mutool` is not installed on the PATH.
   class EmbeddedFontsMissingError < GlyphError; end
 
+  # A `mutool` subprocess exited non-zero. Distinct from
+  # {EmbeddedFontsMissingError}: this fires when mutool ran but failed
+  # (corrupt PDF, bad object ref, etc.). The context carries the argv.
+  class MutoolError < GlyphError; end
+
   # The Code Charts PDF for a requested block cannot be obtained: the
   # network returned 4xx/5xx, the response wasn't application/pdf, or
   # the body didn't start with the `%PDF` magic. Distinct from

data/lib/ucode/glyphs/embedded_fonts/catalog.rb

@@ -17,12 +17,27 @@ module Ucode
       # discovered wins. Discovery order follows mutool info's page-major
       # listing, so earlier blocks' fonts win — the expected behavior.
       class Catalog
-        # @param source [PdfLocation]
+        # @param source [PdfSource]
+        # @param block_range [Range<Integer>, nil] codepoint scope the
+        #   caller is extracting. When present, drops an intrinsic
+        #   strategy's result if it has zero in-block intersection,
+        #   letting positional strategies take over (the U1F200 class
+        #   of failure where the font's CMap encoded composing
+        #   ideographs rather than the specimens). nil = legacy mode
+        #   (intrinsic result always trusted).
+        # @param force_positional_for_font_ids [Set<Integer>] Type0
+        #   font object IDs that always trigger positional attribution
+        #   regardless of intrinsic success. Escape hatch for
+        #   partial-overlap cases.
         # @param correlator_configs [Hash{Integer=>ContentStreamCorrelator::Config}]
         #   maps a Type0 font's PDF object ID to the pillar-2 config to
         #   use when the font has no /ToUnicode CMap. Empty by default.
-        def initialize(source, correlator_configs: {})
+        def initialize(source, block_range: nil,
+                       force_positional_for_font_ids: Set.new,
+                       correlator_configs: {})
           @source = source
+          @block_range = block_range
+          @force_positional_for_font_ids = force_positional_for_font_ids
           @correlator_configs = correlator_configs
           @index = nil
         end
@@ -93,8 +108,10 @@ module Ucode
         end
 
         def mapper
-          @mapper ||= CodepointMapper.new(
+          @mapper ||= CodepointMapper.build(
             source: @source,
+            block_range: @block_range,
+            force_positional_for_font_ids: @force_positional_for_font_ids,
             correlator_configs: @correlator_configs,
             indexer: indexer,
           )

data/lib/ucode/glyphs/embedded_fonts/codepoint_mapper/correlator_strategy.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/strategy"
+require "ucode/glyphs/embedded_fonts/content_stream_correlator"
+require "ucode/glyphs/embedded_fonts/mutool"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      class CodepointMapper
+        # Strategy 2 — caller-supplied pillar-2 config. Renders the
+        # configured pages to SVG and runs {ContentStreamCorrelator}
+        # to match specimen glyphs to hex labels positionally.
+        class CorrelatorStrategy < Strategy
+          # @param source [PdfSource]
+          # @param correlator_configs [Hash{Integer=>ContentStreamCorrelator::Config}]
+          # @param mutool_draw [Mutool::Draw]
+          def initialize(source:, correlator_configs:, mutool_draw:)
+            super()
+            @source = source
+            @correlator_configs = correlator_configs
+            @mutool_draw = mutool_draw
+          end
+
+          def supports?(descriptor)
+            descriptor.cid_map_kind == :identity &&
+              @correlator_configs.key?(descriptor.font_obj_id)
+          end
+
+          # @see Strategy#positional?
+          def positional?
+            true
+          end
+
+          def map(descriptor)
+            config = @correlator_configs[descriptor.font_obj_id]
+            return {} if config.page_numbers.nil? || config.page_numbers.empty?
+
+            svg = @mutool_draw.svg(@source.pdf_to_s, *config.page_numbers)
+            ContentStreamCorrelator.new(config).correlate(svg)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts/codepoint_mapper/strategy.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      class CodepointMapper
+        # Abstract base for the codepoint→GID resolution strategies.
+        #
+        # Each subclass owns ONE mutool subcommand and ONE collaborator.
+        # Subclasses declare their role via {#positional?}:
+        #
+        #   * `positional? == false` — the strategy reads the font's own
+        #     intrinsic mapping (ToUnicode CMap). Authoritative for
+        #     cross-reference typography, but can be misleading when
+        #     the embedded font's CMap encodes composing characters
+        #     rather than the chart specimens (Enclosed Ideographic
+        #     Supplement, where CJKSymbols' CIDs map to the inner CJK
+        #     ideographs, not the squared characters themselves).
+        #   * `positional? == true` — the strategy attributes glyphs to
+        #     codepoints via chart-grid geometry (mutool trace, content
+        #     stream correlation). Authoritative for in-block specimens.
+        #
+        # The orchestrator ({CodepointMapper}) partitions strategies by
+        # this predicate, gates positional strategies behind a
+        # block-scope check, and merges with positional precedence
+        # when both produce a result. Adding a new strategy = one
+        # subclass + one `positional?` override + one entry in the
+        # chain. No edit to CodepointMapper (Open/Closed Principle).
+        class Strategy
+          # @param descriptor [RawFontDescriptor]
+          def supports?(_descriptor)
+            raise NotImplementedError
+          end
+
+          # @param descriptor [RawFontDescriptor]
+          # @return [Hash{Integer=>Integer}] codepoint => gid; empty
+          #   when the strategy cannot produce a mapping
+          def map(_descriptor)
+            raise NotImplementedError
+          end
+
+          # Declares whether this strategy attributes glyphs by chart
+          # geometry (true) or by the font's intrinsic mapping (false).
+          # The default is false; positional strategies override.
+          #
+          # @return [Boolean]
+          def positional?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts/codepoint_mapper/tounicode_strategy.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/strategy"
+require "ucode/glyphs/embedded_fonts/mutool"
+require "ucode/glyphs/embedded_fonts/tounicode"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      class CodepointMapper
+        # Strategy 1 — read the Type0 font's `/ToUnicode` CMap stream
+        # and parse it into a `{codepoint => gid}` map. Highest
+        # fidelity when present; usually missing for subsetted CID
+        # fonts (the case the trace fallback exists for).
+        class ToUnicodeStrategy < Strategy
+          # @param source [PdfSource]
+          # @param mutool_show [Mutool::Show]
+          def initialize(source:, mutool_show:)
+            super()
+            @source = source
+            @mutool_show = mutool_show
+          end
+
+          def supports?(descriptor)
+            descriptor.cid_map_kind == :identity &&
+              !descriptor.tounicode_ref.nil?
+          end
+
+          def map(descriptor)
+            cmap_text = @mutool_show.stream(@source.pdf_to_s,
+                                            descriptor.tounicode_ref)
+            cid_to_cp = ToUnicode.parse(cmap_text)
+            cid_to_cp.each_with_object({}) do |(cid, cp), h|
+              h[cp] = cid
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts/codepoint_mapper/trace_strategy.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/strategy"
+require "ucode/glyphs/embedded_fonts/mutool"
+require "ucode/glyphs/embedded_fonts/page_trace_cache"
+require "ucode/glyphs/embedded_fonts/trace_correlator"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      class CodepointMapper
+        # Strategy 3 — auto-detect via `mutool trace`. Last-resort
+        # fallback for CID fonts without /ToUnicode and without a
+        # caller-supplied correlator config.
+        #
+        # Consumes a {PageTraceCache} that traces each PDF page
+        # exactly once across all CID fonts. The pre-cache path was
+        # O(F × P) subprocess invocations; this is O(P).
+        #
+        # Correlates per page (Y positions are page-local — clustering
+        # across page boundaries would produce false matches).
+        class TraceStrategy < Strategy
+          # @param cache [PageTraceCache, nil] nil = strategy is a no-op
+          # @param indexer [PdfIndexer] for the cheap font_appears?
+          #   precondition (avoids touching the cache for fonts the
+          #   PDF doesn't reference at all)
+          def initialize(cache:, indexer:)
+            super()
+            @cache = cache
+            @indexer = indexer
+          end
+
+          def supports?(descriptor)
+            return false unless @cache
+            return false unless descriptor.cid_map_kind == :identity
+
+            @indexer.font_appears?(descriptor.base_font)
+          end
+
+          # @see Strategy#positional?
+          def positional?
+            true
+          end
+
+          def map(descriptor)
+            return {} unless @cache
+
+            correlator = TraceCorrelator.new(
+              specimen_font_name: descriptor.base_font,
+            )
+            mapping = {}
+            @cache.each_page_for(descriptor.base_font) do |_page, glyphs|
+              page_mapping = correlator.correlate(glyphs)
+              page_mapping.each do |cp, gid|
+                mapping[cp] ||= gid
+              end
+            end
+            mapping
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts/codepoint_mapper.rb

@@ -1,128 +1,181 @@
 # frozen_string_literal: true
 
-require "open3"
-require "pathname"
-require "tempfile"
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/strategy"
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/tounicode_strategy"
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/correlator_strategy"
+require "ucode/glyphs/embedded_fonts/codepoint_mapper/trace_strategy"
+require "ucode/glyphs/embedded_fonts/mutool"
+require "ucode/glyphs/embedded_fonts/page_trace_cache"
+require "ucode/error"
 
 module Ucode
   module Glyphs
     module EmbeddedFonts
-      # Resolves codepoint → GID for one Type0 font via a 3-path strategy:
+      # Resolves codepoint → GID for one Type0 font via a chain of
+      # {Strategy} subclasses.
       #
-      # 1. **ToUnicode CMap** — the font's `/ToUnicode` stream (Tier 1
-      #    for pillar 1). Parsed by {ToUnicode}.
-      # 2. **Caller-supplied correlator config** (pillar 2) — render the
-      #    font's pages to SVG and run {ContentStreamCorrelator}.
-      # 3. **Auto-detect via mutool trace** (pillar 2b) — trace every
-      #    page and run {TraceCorrelator} positionally.
+      # The chain is partitioned by {Strategy#positional?}:
       #
-      # Each path returns a `{codepoint => gid}` map. First non-empty
-      # result wins; the strategy stops there.
+      #   * Intrinsic strategies (ToUnicodeStrategy) read the font's
+      #     own CMap. Tried in chain order; the first non-empty result
+      #     wins.
+      #   * Positional strategies (CorrelatorStrategy, TraceStrategy)
+      #     attribute glyphs by chart-grid geometry. Expensive — they
+      #     shell out to mutool per page — so they only run when an
+      #     intrinsic strategy cannot cover the requested block scope.
       #
-      # Pure strategy orchestration — does NOT parse the PDF object graph
-      # (that's {PdfIndexer}'s job). Takes a {RawFontDescriptor} + the
-      # shared {PdfIndexer} (for page_count + font_appears? queries used
-      # by the trace fallback).
+      # When positional strategies run, their results merge over the
+      # intrinsic result with positional precedence: chart geometry is
+      # authoritative for in-block specimens, while a font's CMap can
+      # be misleading (Enclosed Ideographic Supplement, where the
+      # embedded CJKSymbols font's CMap maps its CIDs to the *composing*
+      # ideographs rather than the squared characters themselves).
+      #
+      # Two escape hatches let callers control the gating:
+      #
+      #   * `block_range:` — when set, an intrinsic result with zero
+      #     in-block intersection is treated as "wrong scope" and
+      #     dropped, so positional strategies can take over. Auto-detect
+      #     for the U1F200 class of failure (Option 1).
+      #   * `force_positional_for_font_ids:` — Type0 font object IDs
+      #     that always go through positional attribution, regardless
+      #     of whether the intrinsic strategy succeeded. Escape hatch
+      #     for partial-overlap cases where the CMap covers some
+      #     in-block codepoints but positional attribution is still
+      #     desired for the rest (Option 2).
+      #
+      # Adding a new strategy = one Strategy subclass + (if positional)
+      # a `positional?` override + one entry in the chain. No edit to
+      # {#map} (Open/Closed Principle).
       class CodepointMapper
-        # @param source [PdfLocation]
-        # @param correlator_configs [Hash{Integer=>ContentStreamCorrelator::Config}]
-        #   caller-supplied pillar-2 configs, keyed by font_obj_id
-        # @param indexer [PdfIndexer] for page_count + font_appears? queries
-        def initialize(source:, correlator_configs:, indexer:)
-          @source = source
-          @correlator_configs = correlator_configs
-          @indexer = indexer
+        # @param strategies [Array<Strategy>] chain; partitioned by
+        #   Strategy#positional? at map time
+        # @param block_range [Range<Integer>, nil] codepoint scope the
+        #   caller is extracting. nil = intrinsic result is always
+        #   trusted (legacy behavior; the caller doesn't know or care
+        #   about block scope).
+        # @param force_positional_for_font_ids [Set<Integer>] Type0
+        #   font object IDs that always trigger positional attribution
+        def initialize(strategies:, block_range: nil,
+                       force_positional_for_font_ids: Set.new)
+          @strategies = strategies
+          @block_range = block_range
+          @force_positional_for_font_ids = force_positional_for_font_ids
+        end
+
+        # Convenience builder — wires up the default 3-strategy chain
+        # with default Mutool wrappers. Callers that need to inject
+        # stubs for tests should construct strategies directly and pass
+        # them to +#initialize+.
+        #
+        # @return [CodepointMapper]
+        def self.build(source:, correlator_configs:, indexer:,
+                       block_range: nil, force_positional_for_font_ids: Set.new,
+                       mutool_show: Mutool::Show.new,
+                       mutool_draw: Mutool::Draw.new,
+                       mutool_trace: Mutool::Trace.new)
+          trace_cache = PageTraceCache.new(
+            pdf: source.pdf_path,
+            page_count: indexer.page_count,
+            mutool: mutool_trace,
+          )
+          strategies = [
+            ToUnicodeStrategy.new(source: source, mutool_show: mutool_show),
+            CorrelatorStrategy.new(source: source,
+                                   correlator_configs: correlator_configs,
+                                   mutool_draw: mutool_draw),
+            TraceStrategy.new(cache: trace_cache, indexer: indexer),
+          ]
+          new(strategies: strategies,
+              block_range: block_range,
+              force_positional_for_font_ids: force_positional_for_font_ids)
         end
 
         # @param descriptor [RawFontDescriptor]
-        # @return [Hash{Integer=>Integer}] codepoint => gid; empty when
-        #   no strategy produces a map
+        # @return [Hash{Integer=>Integer}] codepoint => gid; empty
+        #   when no strategy produces a mapping
         def map(descriptor)
           return {} unless descriptor.cid_map_kind == :identity
 
-          from_tounicode = map_from_tounicode(descriptor.tounicode_ref)
-          return from_tounicode unless from_tounicode.empty?
-
-          from_correlator = map_from_correlator(descriptor.font_obj_id)
-          return from_correlator unless from_correlator.empty?
+          positional, intrinsic = partition_strategies
+          intrinsic_result = run_intrinsic(descriptor, intrinsic)
+          return intrinsic_result if positional.empty?
+          return intrinsic_result unless needs_positional?(descriptor,
+                                                           intrinsic_result)
 
-          map_from_trace(descriptor.base_font)
+          positional_result = run_positional(descriptor, positional)
+          merge_with_positional_precedence(intrinsic_result, positional_result)
         end
 
         private
 
-        # ---- Strategy 1: /ToUnicode CMap --------------------------------
-
-        def map_from_tounicode(tu_ref)
-          return {} unless tu_ref
-
-          cmap_text = fetch_tounicode(tu_ref)
-          cid_to_cp = ToUnicode.parse(cmap_text)
-          build_codepoint_map(cid_to_cp)
+        # `Enumerable#partition` returns `[truthy_group, falsy_group]`,
+        # so the first element is positional strategies and the second
+        # is intrinsic. Naming them explicitly here avoids the
+        # destructure-order footgun.
+        def partition_strategies
+          positional, intrinsic = @strategies.partition(&:positional?)
+          [positional, intrinsic]
         end
 
-        def build_codepoint_map(cid_to_cp)
-          cid_to_cp.each_with_object({}) do |(cid, cp), h|
-            h[cp] = cid
-          end
-        end
+        # Intrinsic chain: first non-empty result wins. preserves the
+        # pre-partition semantics so the legacy ToUnicode-only flow
+        # behaves identically when no positional strategies exist.
+        def run_intrinsic(descriptor, strategies)
+          strategies.each do |s|
+            next unless s.supports?(descriptor)
 
-        def fetch_tounicode(obj_id)
-          Tempfile.create("ucode-tounicode") do |tmp|
-            tmp.close
-            ok = system("mutool", "show", "-o", tmp.path, "-b",
-                        @source.pdf_to_s, obj_id.to_s,
-                        out: File::NULL, err: File::NULL)
-            unless ok
-              raise Ucode::EmbeddedFontsMissingError,
-                    "mutool show failed for ToUnicode obj=#{obj_id}"
-            end
-
-            File.binread(tmp.path).force_encoding("UTF-8")
+            result = s.map(descriptor)
+            return result unless result.empty?
           end
+          {}
         end
 
-        # ---- Strategy 2: caller-supplied correlator config --------------
+        # Positional strategies are gated behind three conditions, any
+        # of which triggers them:
+        #
+        #   1. Caller explicitly listed this font in
+        #      `force_positional_for_font_ids` (Option 2 escape hatch).
+        #   2. No intrinsic strategy produced a mapping (legacy
+        #      fallback for fonts without ToUnicode).
+        #   3. The intrinsic result fell entirely outside the
+        #      caller's block scope — the font's CMap encoded the
+        #      wrong codepoints (Option 1 auto-detect, e.g. U1F200).
+        def needs_positional?(descriptor, intrinsic_result)
+          return true if @force_positional_for_font_ids.include?(descriptor.font_obj_id)
+          return true if intrinsic_result.empty?
+          return true if intrinsic_out_of_scope?(intrinsic_result)
+
+          false
+        end
 
-        def map_from_correlator(font_obj_id)
-          config = @correlator_configs[font_obj_id]
-          return {} unless config
+        def intrinsic_out_of_scope?(intrinsic_result)
+          return false unless @block_range
 
-          svg = render_pages(config.page_numbers)
-          ContentStreamCorrelator.new(config).correlate(svg)
+          intrinsic_result.keys.none? { |cp| @block_range.include?(cp) }
         end
 
-        def render_pages(page_numbers)
-          return "" if page_numbers.nil? || page_numbers.empty?
+        # Positional chain: union of all positional strategies' results.
+        # Within positional, earlier strategies win on conflict (chain
+        # order expresses caller preference — CorrelatorStrategy
+        # before TraceStrategy when both are configured).
+        def run_positional(descriptor, strategies)
+          merged = {}
+          strategies.each do |s|
+            next unless s.supports?(descriptor)
 
-          out, err, status = Open3.capture3(
-            "mutool", "draw", "-F", "svg",
-            @source.pdf_to_s,
-            *page_numbers.map(&:to_s),
-          )
-          unless status.success?
-            raise Ucode::EmbeddedFontsMissingError,
-                  "mutool draw failed: #{err.strip}"
+            s.map(descriptor).each { |cp, gid| merged[cp] ||= gid }
           end
-
-          out
+          merged
         end
 
-        # ---- Strategy 3: auto-detect via mutool trace --------------------
-
-        def map_from_trace(base_font)
-          return {} unless @indexer.font_appears?(base_font)
-
-          runner = TraceRunner.new(@source.pdf_path)
-          correlator = TraceCorrelator.new(specimen_font_name: base_font)
-
-          (1..@indexer.page_count).each_with_object({}) do |page, mapping|
-            glyphs = runner.trace([page])
-            page_mapping = correlator.correlate(glyphs)
-            page_mapping.each do |cp, gid|
-              mapping[cp] ||= gid
-            end
-          end
+        # Merge intrinsic and positional results. Positional wins on
+        # conflict (chart geometry is authoritative for in-block
+        # specimens).
+        def merge_with_positional_precedence(intrinsic, positional)
+          merged = intrinsic.dup
+          positional.each { |cp, gid| merged[cp] = gid }
+          merged
         end
       end
     end

data/lib/ucode/glyphs/embedded_fonts/mutool/draw.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/glyphs/embedded_fonts/mutool"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      module Mutool
+        class Draw
+          def initialize(runner: SystemRunner.new)
+            @runner = runner
+          end
+
+          def svg(pdf, *pages)
+            return "" if pages.empty?
+
+            @runner.run("mutool", "draw", "-F", "svg", pdf.to_s,
+                        *pages.map(&:to_s))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts/mutool/info.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/glyphs/embedded_fonts/mutool"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      module Mutool
+        class Info
+          def initialize(runner: SystemRunner.new)
+            @runner = runner
+          end
+
+          def call(pdf)
+            @runner.run("mutool", "info", pdf.to_s)
+          end
+        end
+      end
+    end
+  end
+end