ucode 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2e60f073662cc78885f8ee6a0333a2307a8b894ddb9789b1e206f6ae63d25e3
-  data.tar.gz: 50b3984de26589d0aab193250e9c8dd3f56fd0d10a4a77a21ffdcb236c38c737
+  metadata.gz: 409561757912083c19e4044c0ed37129945bf6de53bc3b029d349e4a8f16f10f
+  data.tar.gz: 85a06e0383587af4d8a88342974a58105423635b85212ecc7b1783268e6c5e2a
 SHA512:
-  metadata.gz: 88d9ef3df0f99af9b3897cd429666092d48a373d9c60d3c83a6e06a59404e0523c736a8d971fbb6d6d29c9b4b80d9610cad54a64cda439326e19a80670d67ba9
-  data.tar.gz: 8146f6984defddb5b45204fe7a8852cd3051bf1474584eddc7489e5ec9fd4900d48452ac5462a1c6c2ac9b8213823ace68cebe6c5b5176dd0c25c922f8f1d4ba
+  metadata.gz: 85660ae16bbfa2632131888872ddebca9cdee45d26791837ddce2fa629e18a721c9701b023c5424e058165eac03d1d4e1d16bb2a6c0b582a8ef4c1e0104ecdf5
+  data.tar.gz: 411de21c9c5f3e46b559752d54462f02f4110aa59e261ee3ea6c19383ad9383fd43f013e1107fe59b3e6c3b296f906a8c99e7087da5f9c85f2b13ba385447b95

data/Rakefile

@@ -26,4 +26,4 @@ begin
 rescue LoadError
 end
 
-task default: %i[spec rubocop]
+task default: %i[spec rubocop]

data/config/unicode17_universal_glyph_set.yml

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

data/lib/ucode/cli.rb

@@ -109,34 +109,6 @@ module Ucode
       puts JSON.pretty_generate(result)
     end
 
-    # ─────────────── glyphs ───────────────
-    desc "glyphs [VERSION]", "Extract per-codepoint SVGs from Code Charts PDFs (experimental)"
-    long_desc <<~LONG
-      EXPERIMENTAL in v0.1. The cell extractor currently includes cell-border
-      decorations alongside the actual character outline, so the output is not
-      yet suitable for end-user display. Opt in with --include-glyphs to run
-      the pipeline anyway; otherwise it returns a skipped payload.
-    LONG
-    option :to, type: :string, default: "./output"
-    option :block, type: :array, desc: "Limit to these block ids"
-    option :force, type: :boolean, default: false
-    option :monolith, type: :string, default: "CodeCharts.pdf",
-                      desc: "Path to CodeCharts.pdf for fallback slicing"
-    option :include_glyphs, type: :boolean, default: false,
-                            desc: "Opt into the experimental v0.1 pipeline"
-    def glyphs(version = nil)
-      result = Commands::GlyphsCommand.new.call(
-        VersionResolver.resolve(version),
-        output_root: options[:to],
-        block_filter: options[:block],
-        force: options[:force],
-        monolith_path: options[:monolith],
-        include_glyphs: options[:include_glyphs],
-        warn: $stderr,
-      )
-      puts JSON.pretty_generate(result)
-    end
-
     # ─────────────── site ───────────────
     class Site < Thor
       desc "init", "Copy the Vitepress scaffold into site/"
@@ -345,22 +317,16 @@ module Ucode
     subcommand "cache", Cache
 
     # ─────────────── build ───────────────
-    desc "build [VERSION]", "Full pipeline: fetch + parse + (optional) glyphs + site"
+    desc "build [VERSION]", "Full pipeline: fetch + parse + site"
     option :to, type: :string, default: "./output"
     option :site, type: :string, default: nil, desc: "Build the site here (skipped if nil)"
-    option :monolith, type: :string, default: "CodeCharts.pdf"
     option :force_fetch, type: :boolean, default: false
-    option :include_glyphs, type: :boolean, default: false,
-                            desc: "Opt into the experimental v0.1 glyph step"
     def build(version = nil)
       result = Commands::BuildCommand.new.call(
         version,
         output_root: options[:to],
         site_root: options[:site],
-        monolith_path: options[:monolith],
         force_fetch: options[:force_fetch],
-        include_glyphs: options[:include_glyphs],
-        warn: $stderr,
       )
       puts JSON.pretty_generate(result)
     end

data/lib/ucode/commands/build.rb

@@ -8,36 +8,23 @@ require "ucode/version_resolver"
 module Ucode
   module Commands
     # `ucode build` — full pipeline: fetch (ucd + unihan + charts) →
-    # parse → (optional) glyphs → (optional) site. Resumable: each step
-    # is idempotent and safe to re-run.
+    # parse → site. Resumable: each step is idempotent and safe to re-run.
     #
     # Resolves the version intent once at the top and threads the
-    # resolved string through every sub-command. See Candidate 4 of the
-    # 2026-06-29 architecture review.
-    #
-    # **Glyph step is opt-in as of v0.1** because the SVG cell extractor
-    # is still experimental. Pass `include_glyphs: true` to enable it;
-    # otherwise the glyphs step is recorded as skipped.
+    # resolved string through every sub-command.
     class BuildCommand
       # @param version_intent [nil, :default, :latest, String]
       # @param output_root [String, Pathname]
       # @param site_root [String, Pathname, nil] if nil, skip site build
-      # @param monolith_path [String, Pathname, nil] CodeCharts.pdf fallback
       # @param force_fetch [Boolean] re-download sources
-      # @param include_glyphs [Boolean] opt into the experimental glyph
-      #   step (default false)
-      # @param warn [IO, nil] forwarded to GlyphsCommand when enabled
       # @return [Hash] aggregated step results
       def call(version_intent, output_root:, site_root: nil,
-               monolith_path: nil, force_fetch: false,
-               include_glyphs: false, warn: nil)
+               force_fetch: false)
         version = VersionResolver.resolve(version_intent)
         steps = {}
 
         steps[:fetch] = run_fetch(version, force: force_fetch)
         steps[:parse] = ParseCommand.new.call(version, output_root: output_root)
-        steps[:glyphs] = run_glyphs(version, output_root, monolith_path,
-                                     include_glyphs: include_glyphs, warn: warn)
         steps[:site] = run_site(output_root, site_root) if site_root
 
         { version: version, steps: steps }
@@ -54,16 +41,6 @@ module Ucode
         }
       end
 
-      def run_glyphs(version, output_root, monolith_path, include_glyphs:, warn:)
-        GlyphsCommand.new.call(
-          version,
-          output_root: output_root,
-          monolith_path: monolith_path || "CodeCharts.pdf",
-          include_glyphs: include_glyphs,
-          warn: warn,
-        )
-      end
-
       def run_site(output_root, site_root)
         SiteCommand.new.build(output_root: output_root, site_root: site_root)
       end

data/lib/ucode/commands/canonical_build.rb

@@ -20,10 +20,7 @@ module Ucode
     # `index.json` + `glyph.svg` atomically, accumulate per-tier +
     # per-block stats, and emit `output/build-report.json`.
     #
-    # This is the v0.2 replacement for the v0.1 cell-extractor pipeline
-    # in {GlyphsCommand}. The two coexist until the v0.1 pipeline is
-    # removed (TODOs 17-19); CanonicalBuildCommand is the path forward
-    # for production dataset runs.
+    # This is the production path for dataset runs.
     #
     # == Pre-conditions (per TODO 21)
     #

data/lib/ucode/commands.rb

@@ -9,7 +9,6 @@ module Ucode
   module Commands
     autoload :FetchCommand, "ucode/commands/fetch"
     autoload :ParseCommand, "ucode/commands/parse"
-    autoload :GlyphsCommand, "ucode/commands/glyphs"
     autoload :SiteCommand, "ucode/commands/site"
     autoload :LookupCommand, "ucode/commands/lookup"
     autoload :CacheCommand, "ucode/commands/cache"

data/lib/ucode/error.rb

@@ -24,8 +24,6 @@ module Ucode
   #   │   ├── Ucode::DatabaseSchemaError
   #   │   └── Ucode::UnknownVersionError
   #   └── Ucode::GlyphError
-  #       ├── Ucode::PdfRenderError
-  #       ├── Ucode::GridDetectionError
   #       ├── Ucode::LastResortMissingError
   #       ├── Ucode::EmbeddedFontsMissingError
   #       └── Ucode::UniversalSetPreBuildError
@@ -104,12 +102,6 @@ module Ucode
   # Glyph pipeline failures.
   class GlyphError < Error; end
 
-  # PDF → SVG rendering failure.
-  class PdfRenderError < GlyphError; end
-
-  # Grid detection couldn't anchor on codepoint labels.
-  class GridDetectionError < GlyphError; end
-
   # The Last Resort Font UFO source cannot be located or is missing a
   # required artifact (cmap-f13.ttx, font.ufo/glyphs/, contents.plist).
   class LastResortMissingError < GlyphError; end

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

@@ -249,6 +249,7 @@ module Ucode
             font_obj_id: font_obj_id,
             tu_ref: tu_ref,
             cid_map_kind: cid_map_kind,
+            base_font: base_font,
           )
           return nil if cp_to_gid.empty?
 
@@ -275,14 +276,23 @@ module Ucode
         # when no /ToUnicode is present, consult the correlator_configs
         # registry — if the user supplied a config for this font, render
         # the relevant page(s) to SVG and run positional correlation.
-        # Returns an empty hash when neither path produces a map (the
-        # caller treats that as "skip this font").
-        def build_codepoint_to_gid(font_obj_id:, tu_ref:, cid_map_kind:)
+        # Pillar-2b fallback: when no caller-supplied config either,
+        # auto-detect via `mutool trace` — parse the structured text
+        # trace to build `{codepoint => gid}` from hex labels + specimen
+        # positions. Returns an empty hash when none of the paths
+        # produce a map (the caller treats that as "skip this font").
+        def build_codepoint_to_gid(font_obj_id:, tu_ref:, cid_map_kind:,
+                                   base_font: nil)
           return {} if cid_map_kind != :identity
 
           return codepoint_map_from_tounicode(tu_ref) if tu_ref
 
-          codepoint_map_from_correlator(font_obj_id)
+          map = codepoint_map_from_correlator(font_obj_id)
+          return map unless map.empty?
+
+          return {} unless base_font
+
+          codepoint_map_from_trace(base_font, font_obj_id)
         end
 
         def codepoint_map_from_tounicode(tu_ref)
@@ -298,6 +308,73 @@ module Ucode
           ContentStreamCorrelator.new(config).correlate(svg)
         end
 
+        # Pillar-2b: auto-detect codepoint → GID via `mutool trace`.
+        # For CID-keyed fonts without /ToUnicode and without a
+        # caller-supplied correlator config, trace every page of the
+        # PDF and positionally match hex labels to specimen glyphs.
+        # `mutool info` only reports the first page per font, so tracing
+        # all pages is simpler and catches every chart page.
+        #
+        # Each page is correlated independently to prevent cross-page
+        # position interference (page coordinate systems overlap, so
+        # a label on page 3 could wrongly match a specimen on page 2).
+        # First match wins when a codepoint appears on multiple pages.
+        def codepoint_map_from_trace(base_font, _font_obj_id)
+          return {} unless font_appears_in_pdf?(base_font)
+
+          runner = TraceRunner.new(@source.pdf_path)
+          correlator = TraceCorrelator.new(specimen_font_name: base_font)
+
+          (1..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
+        end
+
+        def font_appears_in_pdf?(base_font)
+          font_entries_cache.key?(base_font)
+        end
+
+        # Lazy cache of {base_font => true} — which fonts `mutool info`
+        # reports in this PDF. We only need the key set, not page numbers,
+        # because {codepoint_map_from_trace} traces all pages regardless.
+        def font_entries_cache
+          @font_entries_cache ||= begin
+            result = {}
+            mutool_info_text.each_line do |line|
+              next unless line.include?("Type0")
+
+              font_match = line.match(/Type0\s+'([^']+)'/)
+              next unless font_match
+
+              result[font_match[1]] = true
+            end
+            result
+          end
+        end
+
+        # Total pages in the PDF, parsed from `mutool info`'s
+        # `Pages: N` line. Falls back to the first font page if parsing
+        # fails (so we still try at least one page).
+        def page_count
+          @page_count ||= begin
+            m = mutool_info_text.match(/^Pages:\s+(\d+)/)
+            m ? m[1].to_i : 1
+          end
+        end
+
+        def mutool_info_text
+          @mutool_info_text ||= run_mutool_info
+        end
+
+        def run_mutool_info
+          out, err, status = Open3.capture3("mutool", "info", @source.pdf_to_s)
+          status.success? ? out + err : ""
+        end
+
         def resolve_fontfile(fd_dict)
           if fd_dict.key?("FontFile2")
             [first_ref(fd_dict["FontFile2"]), :ttf]

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

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Correlates specimen glyphs (CID font without `/ToUnicode`) to
+      # their Unicode codepoints via positional matching against hex
+      # codepoint labels on the same chart page.
+      #
+      # The Unicode Code Charts use two layouts:
+      #
+      # 1. **List layout** (chart pages): the hex codepoint label (e.g.
+      #    "10D75") is printed to the LEFT of the specimen glyph at the
+      #    same Y baseline.
+      #
+      # 2. **Grid layout** (summary pages): the hex codepoint label is
+      #    printed directly ABOVE the specimen glyph (~12 pt higher on
+      #    Y, same X).
+      #
+      # Both layouts are handled by matching each specimen to the
+      # nearest valid label cluster by Euclidean distance, with a
+      # maximum match radius that excludes far-away header/footer text.
+      #
+      # The codepoint labels in every Unicode Code Charts PDF are set
+      # in a single dedicated label font (typically ArialNarrow).
+      # Character names, headers, and footers use other fonts. To avoid
+      # false matches from hex chars in those texts, the correlator
+      # auto-detects the label font as the non-specimen font that
+      # contributes the most hex-char glyphs.
+      #
+      # Matching is greedy one-to-one: each GID and each codepoint is
+      # assigned at most once, so a specimen that sits between two
+      # labels only claims the closer one.
+      #
+      # Pure logic — no I/O. The caller passes pre-parsed TraceGlyph
+      # arrays (typically from {TraceRunner} + {TraceParser}).
+      class TraceCorrelator
+        DEFAULT_Y_BUCKET = 1.0
+        private_constant :DEFAULT_Y_BUCKET
+
+        # Adjacent label chars within one codepoint label are ~4-6 pt
+        # apart on X. Different columns are ~30+ pt apart. 10 pt
+        # cleanly separates within-label from between-column gaps.
+        X_GAP_THRESHOLD = 10.0
+        private_constant :X_GAP_THRESHOLD
+
+        # Maximum valid Unicode codepoint. Filters out false labels
+        # that form hex strings from character-name fragments.
+        UNICODE_MAX = 0x10FFFF
+        private_constant :UNICODE_MAX
+
+        # Maximum Euclidean distance from a specimen to its matching
+        # label cluster. List-layout labels are ~21 pt to the left;
+        # grid-layout labels are ~12 pt above. Header/footer text is
+        # always > 30 pt away from any specimen.
+        MAX_MATCH_DISTANCE = 30.0
+        private_constant :MAX_MATCH_DISTANCE
+
+        # @param specimen_font_name [String] the BaseFont name of the
+        #   CID font whose glyphs need correlation
+        def initialize(specimen_font_name:)
+          @specimen_font_name = specimen_font_name
+          @y_bucket = DEFAULT_Y_BUCKET
+        end
+
+        # @param trace_glyphs [Array<TraceGlyph>]
+        # @return [Hash{Integer=>Integer}] codepoint => gid
+        def correlate(trace_glyphs)
+          specimens = trace_glyphs.select { |g| g.font_name == @specimen_font_name }
+          return {} if specimens.empty?
+
+          label_font = detect_label_font(trace_glyphs)
+          return {} unless label_font
+
+          labels = trace_glyphs.select { |g| label_glyph?(g, label_font) }
+          return {} if labels.empty?
+
+          clusters = build_label_clusters(labels)
+          return {} if clusters.empty?
+
+          build_mapping(specimens, clusters)
+        end
+
+        private
+
+        # The label font is the non-specimen font whose hex-char glyphs
+        # appear most often in close proximity to specimen glyphs.
+        # Code Charts dedicate one small font to the codepoint labels;
+        # body text, headers, and character names use other fonts that
+        # may also contain hex chars but are not co-located with
+        # specimens (e.g. the index page has thousands of hex chars in
+        # MyriadPro-Light but zero specimens).
+        LABEL_PROXIMITY_RADIUS = 50.0
+        private_constant :LABEL_PROXIMITY_RADIUS
+
+        def detect_label_font(trace_glyphs)
+          specimens = trace_glyphs.select { |g| g.font_name == @specimen_font_name }
+          return nil if specimens.empty?
+
+          non_specimen_hex = non_specimen_hex_glyphs(trace_glyphs)
+          return nil if non_specimen_hex.empty?
+
+          counts = proximity_counts(specimens, non_specimen_hex)
+          return nil if counts.empty?
+
+          counts.max_by { |_, n| n }.first
+        end
+
+        def non_specimen_hex_glyphs(trace_glyphs)
+          trace_glyphs.select do |g|
+            g.font_name != @specimen_font_name &&
+              g.unicode&.match?(/\A[0-9A-Fa-f]\z/)
+          end
+        end
+
+        def proximity_counts(specimens, candidates)
+          counts = Hash.new(0)
+          radius_sq = LABEL_PROXIMITY_RADIUS * LABEL_PROXIMITY_RADIUS
+          specimens.each do |spec|
+            candidates.each do |g|
+              counts[g.font_name] += 1 if within_radius?(spec, g, radius_sq)
+            end
+          end
+          counts
+        end
+
+        def within_radius?(spec, glyph, radius_sq)
+          dx = spec.x - glyph.x
+          dy = spec.y - glyph.y
+          dx * dx + dy * dy < radius_sq
+        end
+
+        def label_glyph?(glyph, label_font)
+          glyph.font_name == label_font &&
+            glyph.unicode&.match?(/\A[0-9A-Fa-f]\z/)
+        end
+
+        # Cluster labels by Y (row), then by X gap (column within row).
+        # Returns a flat array of {x:, y:, codepoint:} clusters.
+        def build_label_clusters(labels)
+          by_y = labels.group_by { |g| quantize(g.y, @y_bucket) }
+          by_y.flat_map { |(_, glyphs)| clusters_from_row(glyphs) }
+        end
+
+        def clusters_from_row(glyphs)
+          cluster_by_x_gap(glyphs.sort_by(&:x)).filter_map { |cluster| build_cluster(cluster) }
+        end
+
+        def build_cluster(cluster)
+          hex = cluster.map(&:unicode).join
+          return nil unless hex.match?(/\A[0-9A-Fa-f]{4,6}\z/)
+
+          cp = hex.to_i(16)
+          return nil unless cp <= UNICODE_MAX
+
+          {
+            x: cluster.sum(&:x) / cluster.size,
+            y: cluster.first.y,
+            codepoint: cp,
+          }
+        end
+
+        def cluster_by_x_gap(sorted_glyphs)
+          clusters = []
+          current = []
+
+          sorted_glyphs.each do |g|
+            if current.empty? || (g.x - current.last.x).abs < X_GAP_THRESHOLD
+              current << g
+            else
+              clusters << current if current.size > 1
+              current = [g]
+            end
+          end
+          clusters << current if current.size > 1
+          clusters
+        end
+
+        # Greedy one-to-one matching: each GID and each codepoint is
+        # assigned at most once. Candidate pairs are sorted by distance
+        # so the closest specimen-label pair always wins.
+        def build_mapping(specimens, clusters)
+          candidates = Array.new(clusters.size) { |ci| specimen_distances(specimens, clusters, ci) }
+
+          assigned_gids = Set.new
+          assigned_cps = Set.new
+          mapping = {}
+
+          pairs_by_distance(candidates).each do |spec_idx, cluster_idx, dist|
+            next if dist > MAX_MATCH_DISTANCE
+
+            spec = specimens[spec_idx]
+            cluster = clusters[cluster_idx]
+            next if assigned_gids.include?(spec.gid)
+            next if assigned_cps.include?(cluster[:codepoint])
+
+            assigned_gids << spec.gid
+            assigned_cps << cluster[:codepoint]
+            mapping[cluster[:codepoint]] = spec.gid
+          end
+
+          mapping
+        end
+
+        def specimen_distances(specimens, clusters, cluster_idx)
+          cluster = clusters[cluster_idx]
+          specimens.each_with_index.map do |spec, spec_idx|
+            [spec_idx, cluster_idx, distance(spec, cluster)]
+          end
+        end
+
+        def pairs_by_distance(candidates)
+          candidates.flatten(1).sort_by { |_, _, dist| dist }
+        end
+
+        def distance(spec, cluster)
+          dx = spec.x - cluster[:x]
+          dy = spec.y - cluster[:y]
+          Math.sqrt(dx * dx + dy * dy)
+        end
+
+        def quantize(value, bucket_size)
+          return nil if value.nil?
+
+          (value / bucket_size).round * bucket_size
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Value object for one glyph emitted by `mutool trace`.
+      #
+      # Each `<g>` element in the trace XML maps to one TraceGlyph:
+      #
+      #   <g unicode="�" glyph="174" x="237.06" y="673.92" adv=".62"/>
+      #
+      # The `font_name` is inherited from the enclosing `<span>`:
+      #
+      #   <span font="GPJAHB+WolofGaraySansSerif" ...>
+      #       <g .../>
+      #   </span>
+      TraceGlyph = Struct.new(
+        :font_name,
+        :gid,
+        :x,
+        :y,
+        :unicode,
+        keyword_init: true,
+      )
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Parses the XML output of `mutool trace <pdf> <page>` into an
+      # array of {TraceGlyph} instances.
+      #
+      # The trace XML uses a flat `<span font="...">` → `<g glyph="..."
+      # x="..." y="..." unicode="..."/>` structure. Nokogiri walks
+      # the tree; the parser maps each `<g>` to a TraceGlyph,
+      # inheriting the font_name from the enclosing span.
+      #
+      # Pure function — no I/O, no PDF access. Callers inject the XML
+      # string (typically from {TraceRunner}).
+      module TraceParser
+        class << self
+          # @param xml [String] raw mutool trace XML
+          # @return [Array<TraceGlyph>] one per `<g>` element; empty
+          #   if the XML is empty or has no `<g>` elements
+          def parse(xml)
+            return [] if xml.nil? || xml.strip.empty?
+
+            doc = Nokogiri::XML(xml)
+            doc.css("span").flat_map { |span| glyphs_in_span(span) }
+          end
+
+          private
+
+          def glyphs_in_span(span)
+            font_name = span[:font]
+            span.css("g").map { |g| build_glyph(font_name, g) }
+          end
+
+          def build_glyph(font_name, g)
+            TraceGlyph.new(
+              font_name: font_name,
+              gid: g[:glyph]&.to_i,
+              x: g[:x]&.to_f,
+              y: g[:y]&.to_f,
+              unicode: g[:unicode],
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "open3"
+require "pathname"
+
+require "ucode/error"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Thin I/O wrapper around `mutool trace <pdf> <page>`.
+      #
+      # Runs mutool on the given pages, captures the XML output,
+      # delegates parsing to {TraceParser}, and returns a flat
+      # `Array<TraceGlyph>` across all pages.
+      #
+      # The only class in the trace pipeline that touches the
+      # filesystem / spawns subprocesses. Everything upstream
+      # (parser, correlator) is pure.
+      class TraceRunner
+        # @param pdf_path [Pathname, String]
+        def initialize(pdf_path)
+          @pdf_path = Pathname.new(pdf_path)
+        end
+
+        # @param page_numbers [Array<Integer>] 1-based PDF page numbers
+        # @return [Array<TraceGlyph>]
+        def trace(page_numbers)
+          page_numbers.flat_map { |page| trace_page(page) }
+        end
+
+        private
+
+        def trace_page(page)
+          xml = run_mutool(page)
+          TraceParser.parse(xml)
+        end
+
+        def run_mutool(page)
+          out, err, status = Open3.capture3(
+            "mutool", "trace", @pdf_path.to_s, page.to_s,
+          )
+          unless status.success?
+            raise Ucode::EmbeddedFontsMissingError,
+                  "mutool trace failed: #{(out + err).strip}"
+          end
+
+          out + err
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts.rb

@@ -42,6 +42,10 @@ module Ucode
       autoload :Catalog, "ucode/glyphs/embedded_fonts/catalog"
       autoload :ContentStreamCorrelator,
                "ucode/glyphs/embedded_fonts/content_stream_correlator"
+      autoload :TraceGlyph, "ucode/glyphs/embedded_fonts/trace_glyph"
+      autoload :TraceParser, "ucode/glyphs/embedded_fonts/trace_parser"
+      autoload :TraceCorrelator, "ucode/glyphs/embedded_fonts/trace_correlator"
+      autoload :TraceRunner, "ucode/glyphs/embedded_fonts/trace_runner"
       autoload :Svg, "ucode/glyphs/embedded_fonts/svg"
       autoload :Renderer, "ucode/glyphs/embedded_fonts/renderer"
       autoload :Writer, "ucode/glyphs/embedded_fonts/writer"