ucode 0.1.0 → 0.1.1

data/lib/ucode/coordinator.rb

@@ -123,7 +123,18 @@ module Ucode
         standardized_variants: multi_cp_index_by_id(ucd_dir, "StandardizedVariants.txt",
                                                     Parsers::StandardizedVariants, :base_id),
         names_list: names_list_index(ucd_dir),
-        unihan: unihan_index(unihan_dir)
+        unihan: unihan_index(unihan_dir),
+        line_break: range_value_index(ucd_dir, "LineBreak.txt"),
+        east_asian_width: range_value_index(ucd_dir, "EastAsianWidth.txt"),
+        vertical_orientation: range_value_index(ucd_dir, "VerticalOrientation.txt"),
+        grapheme_break: range_value_index(ucd_dir, "auxiliary/GraphemeBreakProperty.txt"),
+        word_break: range_value_index(ucd_dir, "auxiliary/WordBreakProperty.txt"),
+        sentence_break: range_value_index(ucd_dir, "auxiliary/SentenceBreakProperty.txt"),
+        indic_positional: range_value_index(ucd_dir, "IndicPositionalCategory.txt"),
+        indic_syllabic: range_value_index(ucd_dir, "IndicSyllabicCategory.txt"),
+        hangul_syllable_type: range_value_index(ucd_dir, "HangulSyllableType.txt"),
+        emoji_properties: range_value_index(ucd_dir, "emoji/emoji-data.txt"),
+        extra_binary_properties: range_value_index(ucd_dir, "PropList.txt"),
       )
     end
 
@@ -136,6 +147,23 @@ module Ucode
       parser.each_record(path).to_a.sort_by(&:range_first)
     end
 
+    # Builds a sorted array of (range_first, range_last, value) tuples for
+    # any UCD file using the standard `XXXX[..YYYY]; value` format. Used
+    # for the many extracted/auxiliary/root properties that share this
+    # shape: LineBreak, EastAsianWidth, VerticalOrientation, the three
+    # break-segmentation files, the two Indic category files,
+    # HangulSyllableType, emoji-data, PropList, etc.
+    #
+    # Tuple is `Parsers::ExtractedProperties::Tuple` — a Struct with
+    # `range_first`, `range_last`, `value` accessors, suitable for the
+    # coordinator's `find_in_range` bsearch.
+    def range_value_index(ucd_dir, filename)
+      path = Pathname.new(ucd_dir).join(filename)
+      return [] unless path.exist?
+
+      Parsers::ExtractedProperties.each_record(path).to_a.sort_by(&:range_first)
+    end
+
     # Builds the sorted Script array and resolves each Script's ISO 15924
     # code in one pass, using the pre-computed property_value_aliases map.
     # This avoids re-resolving the alias on every per-cp lookup (160k ×
@@ -210,12 +238,11 @@ module Ucode
       dir = Pathname.new(unihan_dir)
       return {} unless dir.exist?
 
-      by_field = Hash.new { |h, k| h[k] = {} }
+      entries = Hash.new { |h, k| h[k] = Models::UnihanEntry.new }
       Parsers::Unihan.each_in_dir(dir) do |record|
-        by_field[record.cp][record.field] = record.field_values
+        entries[record.cp].add(record.category, record.field, record.field_values)
       end
-
-      by_field.transform_values { |fields| Models::UnihanEntry.new(fields: fields) }
+      entries
     end
 
     # ---- Per-codepoint enrichment --------------------------------------
@@ -235,6 +262,12 @@ module Ucode
       assign_standardized_variants(cp, indices)
       assign_unihan(cp, indices)
       assign_cjk_radical(cp, indices)
+      assign_display(cp, indices)
+      assign_break_segmentation(cp, indices)
+      assign_indic(cp, indices)
+      assign_hangul(cp, indices)
+      assign_emoji(cp, indices)
+      assign_extra_binary_properties(cp, indices)
     end
 
     def assign_script(cp, indices)
@@ -369,6 +402,106 @@ module Ucode
       end
     end
 
+    # Display: East Asian Width, Line Break Class, Vertical Orientation.
+    # All three are range+value files, looked up via bsearch on sorted
+    # arrays of ExtractedProperties::Tuple.
+    def assign_display(cp, indices)
+      tuple = find_in_range(cp.cp, indices.line_break)
+      lb = tuple&.value
+      tuple = find_in_range(cp.cp, indices.east_asian_width)
+      eaw = tuple&.value
+      tuple = find_in_range(cp.cp, indices.vertical_orientation)
+      vo = tuple&.value
+      return if lb.nil? && eaw.nil? && vo.nil?
+
+      cp.display ||= Models::CodePoint::Display.new
+      cp.display.line_break_class = lb if lb
+      cp.display.east_asian_width = eaw if eaw
+      cp.display.vertical_orientation = vo if vo
+    end
+
+    # UAX #29 segmentation: Grapheme / Word / Sentence break class.
+    def assign_break_segmentation(cp, indices)
+      grapheme = find_in_range(cp.cp, indices.grapheme_break)&.value
+      word = find_in_range(cp.cp, indices.word_break)&.value
+      sentence = find_in_range(cp.cp, indices.sentence_break)&.value
+      return if grapheme.nil? && word.nil? && sentence.nil?
+
+      cp.break_segmentation ||= Models::CodePoint::BreakSegmentation.new
+      cp.break_segmentation.grapheme = grapheme if grapheme
+      cp.break_segmentation.word = word if word
+      cp.break_segmentation.sentence = sentence if sentence
+    end
+
+    def assign_indic(cp, indices)
+      positional = find_in_range(cp.cp, indices.indic_positional)&.value
+      syllabic = find_in_range(cp.cp, indices.indic_syllabic)&.value
+      return if positional.nil? && syllabic.nil?
+
+      cp.indic ||= Models::CodePoint::Indic.new
+      cp.indic.positional_category = positional if positional
+      cp.indic.syllabic_category = syllabic if syllabic
+    end
+
+    def assign_hangul(cp, indices)
+      tuple = find_in_range(cp.cp, indices.hangul_syllable_type)
+      return unless tuple
+
+      cp.hangul ||= Models::CodePoint::HangulSyllable.new
+      cp.hangul.type = tuple.value
+    end
+
+    # Emoji property bundle. Each Emoji_* property from emoji-data.txt
+    # flips the matching boolean on the Emoji sub-model.
+    def assign_emoji(cp, indices)
+      return unless find_in_range(cp.cp, indices.emoji_properties)
+
+      props = all_range_values(cp.cp, indices.emoji_properties)
+      return if props.empty?
+
+      cp.emoji ||= Models::CodePoint::Emoji.new
+      props.each do |prop|
+        case prop
+        when "Emoji"                              then cp.emoji.is_emoji = true
+        when "Emoji_Presentation"                 then cp.emoji.is_presentation_default = true
+        when "Emoji_Modifier"                     then cp.emoji.is_modifier = true
+        when "Emoji_Modifier_Base"                then cp.emoji.is_base = true
+        when "Emoji_Component"                    then cp.emoji.is_component = true
+        when "Extended_Pictographic"              then cp.emoji.is_extended_pictographic = true
+        end
+      end
+    end
+
+    # PropList.txt carries binary properties beyond what's in
+    # DerivedCoreProperties (White_Space, Hyphen, Variation_Selector,
+    # etc.). Merge into the same binary_properties list.
+    def assign_extra_binary_properties(cp, indices)
+      extras = all_range_values(cp.cp, indices.extra_binary_properties)
+      return if extras.empty?
+
+      cp.binary_properties.concat(extras)
+      cp.binary_properties.uniq!
+    end
+
+    # Returns every value whose range contains `cp` in a sorted tuple
+    # array. Most codepoint+property pairs match at most one range, but
+    # a codepoint can carry multiple binary properties from PropList or
+    # emoji-data, so we collect them all.
+    def all_range_values(cp, sorted_ranges)
+      return [] if sorted_ranges.nil? || sorted_ranges.empty?
+
+      values = []
+      sorted_ranges.each do |record|
+        next if cp < record.range_first
+        break if cp > record.range_last && record.range_first > cp
+
+        if cp >= record.range_first && cp <= record.range_last
+          values << record.value
+        end
+      end
+      values
+    end
+
     # ---- Range lookup (bsearch) ----------------------------------------
 
     # Finds the range-containing record in a sorted array via bsearch.

data/lib/ucode/error.rb

@@ -12,7 +12,10 @@ module Ucode
   #   Ucode::Error
   #   ├── Ucode::FetchError
   #   │   ├── Ucode::NetworkError
-  #   │   └── Ucode::ChecksumError
+  #   │   ├── Ucode::ChecksumError
+  #   │   │   └── Ucode::FontChecksumError
+  #   │   ├── Ucode::FontLicenseError
+  #   │   └── Ucode::FontExtractMemberMissingError
   #   ├── Ucode::ParseError
   #   │   ├── Ucode::MalformedLineError
   #   │   └── Ucode::UnknownPropertyError
@@ -24,7 +27,8 @@ module Ucode
   #       ├── Ucode::PdfRenderError
   #       ├── Ucode::GridDetectionError
   #       ├── Ucode::LastResortMissingError
-  #       └── Ucode::EmbeddedFontsMissingError
+  #       ├── Ucode::EmbeddedFontsMissingError
+  #       └── Ucode::UniversalSetPreBuildError
   class Error < StandardError
     attr_reader :context
 
@@ -56,6 +60,22 @@ module Ucode
   # Checksum or integrity failure.
   class ChecksumError < FetchError; end
 
+  # SHA256 of a downloaded specialist font does not match the value
+  # declared in `config/specialist_fonts.yml`. Distinct from
+  # {ChecksumError} so callers can rescue the font-pipeline failure
+  # without catching every generic checksum mismatch.
+  class FontChecksumError < ChecksumError; end
+
+  # A specialist font has a non-OFL license and the caller did not
+  # pass `--allow-proprietary`. Hard guard against pulling
+  # non-redistributable fonts into `data/fonts/`.
+  class FontLicenseError < FetchError; end
+
+  # A `extract: true` manifest entry's `extract_member` is missing
+  # from the downloaded zip. The zip was fetched correctly but does
+  # not contain what we expected.
+  class FontExtractMemberMissingError < FetchError; end
+
   # Parse-time failures.
   class ParseError < Error; end
 
@@ -93,4 +113,12 @@ module Ucode
   # The Code Charts PDF (per-block or monolith) cannot be located, or
   # `mutool` is not installed on the PATH.
   class EmbeddedFontsMissingError < GlyphError; end
+
+  # Pre-build validation failed for a universal-set build. The
+  # context carries the failing checks so the CLI can render a
+  # useful diagnostic without re-running them. Distinct from
+  # {EmbeddedFontsMissingError} because pre-build covers more than
+  # just PDFs: source config schema, font file presence, coverage
+  # assertion.
+  class UniversalSetPreBuildError < GlyphError; end
 end

data/lib/ucode/fetch/font_fetcher/result.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Fetch
+    module FontFetcher
+      STATUSES = %i[downloaded skipped failed local planned].freeze
+      private_constant :STATUSES
+
+      # Typed outcome of fetching one font. The fetcher never raises
+      # for a single font failure; it returns a `:failed` Result so
+      # the aggregate run can keep going and report every problem.
+      #
+      # Statuses:
+      # - `:downloaded` — fetched this run; bytes are on disk at `path`.
+      # - `:skipped`    — already present with matching SHA256 (or dry-run).
+      # - `:failed`     — license refused, checksum mismatch, network
+      #                   error, or zip extraction error. `error` is set.
+      # - `:local`      — `url: null`; the user supplies the file. May
+      #                   or may not be present yet (see `note`).
+      # - `:planned`    — dry-run only; this entry would have been fetched.
+      Result = Struct.new(:status, :label, :path, :size_bytes, :license,
+                          :provenance, :error, :note, keyword_init: true) do
+        def initialize(status:, **opts)
+          unless STATUSES.include?(status)
+            raise ArgumentError, "unknown FontFetcher::Result status: #{status.inspect}"
+          end
+
+          super
+        end
+
+        def downloaded? = status == :downloaded
+        def skipped? = status == :skipped
+        def failed? = status == :failed
+        def local? = status == :local
+        def planned? = status == :planned
+      end
+    end
+  end
+end

data/lib/ucode/fetch/font_fetcher.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Fetch
+    # Namespace for font-pipeline fetchers. Owns the shared {Result}
+    # value object; concrete fetchers live as peer classes in
+    # {Ucode::Fetch} (e.g. {SpecialistFontFetcher}).
+    #
+    # Open/closed: adding a new font source = adding a new fetcher
+    # class that produces {Result} instances. The protocol is the
+    # `Result`, not an abstract base class.
+    module FontFetcher
+      autoload :Result, "ucode/fetch/font_fetcher/result"
+    end
+  end
+end

data/lib/ucode/fetch/specialist_font_fetcher.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "pathname"
+require "tmpdir"
+require "zip"
+
+require "ucode/error"
+require "ucode/fetch/font_fetcher"
+require "ucode/fetch/http"
+require "ucode/models/specialist_font_manifest"
+
+module Ucode
+  module Fetch
+    # Concrete font fetcher: walks a {Models::SpecialistFontManifest}
+    # and materializes each font's `path` on disk.
+    #
+    # Behavior (per acceptance in TODO 30):
+    #
+    # - **Idempotent.** A font whose `path` already exists with the
+    #   manifest's SHA256 is `:skipped`. A file with a mismatched hash
+    #   is re-downloaded.
+    # - **Hashed.** On download, SHA256 is computed. If the manifest
+    #   has a hash, mismatch raises {Ucode::FontChecksumError}. If the
+    #   manifest hash is null, the computed hash is written back to the
+    #   YAML at the end of the run (atomic write).
+    # - **License-checked.** Non-OFL entries require `allow_proprietary:
+    #   true`; otherwise the result is `:failed` with {Ucode::FontLicenseError}.
+    # - **Extracted.** `extract: true` entries unzip to a temp dir and
+    #   only `extract_member` is moved into place.
+    # - **Local-only.** `url: null` entries are never fetched over the
+    #   network; the result is `:local` whether or not the file is yet
+    #   present (with a `note` instructing placement when missing).
+    #
+    # A single font failure does not abort the run. The fetcher returns
+    # an array of {FontFetcher::Result}; the caller decides how to
+    # report failures.
+    class SpecialistFontFetcher
+      # @param manifest_path [String, Pathname] path to the YAML manifest.
+      #   The file is rewritten in place when SHA256 hashes are populated.
+      # @param fonts_root [String, Pathname] root for relative `path:`
+      #   values. Defaults to the project root (current working dir).
+      #   Absolute paths in the manifest bypass this.
+      # @param allow_proprietary [Boolean] when true, non-OFL entries
+      #   are fetched; when false, they produce a `:failed` result.
+      # @param dry_run [Boolean] when true, no network or disk writes;
+      #   each font that would have been fetched yields a `:planned`
+      #   result.
+      # @param http [Module, nil] injectable HTTP module responding to
+      #   `.get(url, dest:)`. Defaults to {Fetch::Http}. Real-in-class
+      #   test stubs can substitute a module that writes local fixture
+      #   bytes; never use a double.
+      def initialize(manifest_path:, fonts_root: ".", allow_proprietary: false,
+                     dry_run: false, http: Fetch::Http)
+        @manifest_path = Pathname.new(manifest_path)
+        @fonts_root = Pathname.new(fonts_root)
+        @allow_proprietary = allow_proprietary
+        @dry_run = dry_run
+        @http = http
+        @computed_hashes = {}
+      end
+
+      # @param only_label [String, nil] restrict the run to a single
+      #   manifest entry by label. nil (default) = run all entries.
+      # @return [Array<FontFetcher::Result>] one per manifest entry
+      #   actually visited, in declared order.
+      def call(only_label: nil)
+        manifest = load_manifest
+        return [unknown_label_result(only_label)] if only_label && manifest.find_by_label(only_label).nil?
+
+        entries = only_label ? [manifest.find_by_label(only_label)] : manifest.fonts
+        results = entries.map { |font| fetch_one(font) }
+        persist_computed_hashes(manifest) unless @dry_run
+        results
+      end
+
+      private
+
+      def load_manifest
+        Ucode::Models::SpecialistFontManifest.from_yaml(@manifest_path.read)
+      end
+
+      def unknown_label_result(label)
+        FontFetcher::Result.new(
+          status: :failed,
+          label: label,
+          error: Ucode::LookupError.new(
+            "label #{label.inspect} is not in #{@manifest_path}",
+            context: { manifest: @manifest_path.to_s, requested_label: label },
+          ),
+        )
+      end
+
+      def fetch_one(font)
+        if font.local_only?
+          local_result(font)
+        elsif @dry_run
+          dry_run_result(font)
+        else
+          download_result(font)
+        end
+      end
+
+      def local_result(font)
+        resolved = expand_local_path(font.path)
+        existing = resolved.find(&:exist?)
+        if existing
+          FontFetcher::Result.new(
+            status: :local,
+            label: font.label,
+            path: existing,
+            size_bytes: existing.size,
+            license: font.license,
+            provenance: font.provenance,
+          )
+        else
+          FontFetcher::Result.new(
+            status: :local,
+            label: font.label,
+            path: font.path,
+            license: font.license,
+            provenance: font.provenance,
+            note: "place at #{font.path}",
+          )
+        end
+      end
+
+      def dry_run_result(font)
+        existing = destination_path(font)
+        if existing&.exist? && hash_matches?(existing, font)
+          FontFetcher::Result.new(status: :skipped, label: font.label,
+                                  path: existing, license: font.license,
+                                  provenance: font.provenance)
+        else
+          FontFetcher::Result.new(status: :planned, label: font.label,
+                                  path: destination_for_display(font),
+                                  license: font.license,
+                                  provenance: font.provenance)
+        end
+      end
+
+      def download_result(font)
+        unless font.ofl? || @allow_proprietary
+          return FontFetcher::Result.new(
+            status: :failed, label: font.label, license: font.license,
+            error: Ucode::FontLicenseError.new(
+              "#{font.label} license=#{font.license.inspect} requires --allow-proprietary",
+              context: { label: font.label, license: font.license },
+            ),
+          )
+        end
+
+        dest = destination_path(font)
+        return skipped_result(font, dest) if dest.exist? && hash_matches?(dest, font)
+
+        download_and_install(font, dest)
+      rescue Ucode::Error => e
+        FontFetcher::Result.new(status: :failed, label: font.label,
+                                license: font.license, error: e)
+      rescue StandardError => e
+        FontFetcher::Result.new(status: :failed, label: font.label,
+                                license: font.license,
+                                error: Ucode::FetchError.new(
+                                  "#{font.label} fetch failed: #{e.class}: #{e.message}",
+                                  context: { label: font.label, original: e.class.name },
+                                ))
+      end
+
+      def skipped_result(font, dest)
+        FontFetcher::Result.new(status: :skipped, label: font.label,
+                                path: dest, size_bytes: dest.size,
+                                license: font.license, provenance: font.provenance)
+      end
+
+      def download_and_install(font, dest)
+        dest.dirname.mkpath
+        if font.extract?
+          download_and_extract(font, dest)
+        else
+          @http.get(font.url, dest: dest.to_s)
+        end
+        verify_or_record_hash(font, dest)
+        FontFetcher::Result.new(status: :downloaded, label: font.label,
+                                path: dest, size_bytes: dest.size,
+                                license: font.license, provenance: font.provenance)
+      end
+
+      def download_and_extract(font, dest)
+        Dir.mktmpdir("ucode-font-") do |tmp|
+          zip_path = File.join(tmp, "download.zip")
+          @http.get(font.url, dest: zip_path)
+          extract_member(zip_path, font.extract_member, dest)
+        end
+      end
+
+      def extract_member(zip_path, member_name, dest)
+        Zip::File.open(zip_path) do |zip|
+          entry = zip.find_entry(member_name) ||
+            zip.find { |e| !e.directory? && e.name.end_with?("/#{member_name}", member_name) }
+          unless entry
+            raise Ucode::FontExtractMemberMissingError.new(
+              "zip #{File.basename(zip_path)} does not contain #{member_name.inspect}",
+              context: { zip: zip_path, expected_member: member_name },
+            )
+          end
+
+          entry.get_input_stream do |input|
+            File.open(dest, "wb") { |out| IO.copy_stream(input, out) }
+          end
+        end
+      end
+
+      def verify_or_record_hash(font, dest)
+        actual = sha256_of(dest)
+        if font.hash_known?
+          unless actual.casecmp(font.sha256).zero?
+            raise Ucode::FontChecksumError.new(
+              "#{font.label} SHA256 mismatch: expected #{font.sha256}, got #{actual}",
+              context: { label: font.label, expected: font.sha256, actual: actual },
+            )
+          end
+        else
+          @computed_hashes[font.label] = actual
+        end
+      end
+
+      def hash_matches?(path, font)
+        return true unless font.hash_known?
+
+        sha256_of(path).casecmp?(font.sha256)
+      end
+
+      def sha256_of(path)
+        Digest::SHA256.file(path.to_s).hexdigest
+      end
+
+      def destination_path(font)
+        return nil if font.path.nil? || font.path.empty?
+
+        path = expand_path_for_display(font.path)
+        return path if path.absolute?
+
+        @fonts_root.join(path)
+      end
+
+      def destination_for_display(font)
+        destination_path(font) || font.path
+      end
+
+      def expand_path_for_display(raw)
+        return Pathname.new(raw) unless raw.start_with?("~")
+
+        Pathname.new(File.expand_path(raw))
+      end
+
+      def expand_local_path(raw)
+        expanded = File.expand_path(raw)
+        Dir.glob(expanded).map { |p| Pathname.new(p) }
+      end
+
+      def persist_computed_hashes(manifest)
+        return if @computed_hashes.empty?
+
+        manifest.fonts.each do |font|
+          next unless @computed_hashes.key?(font.label)
+
+          font.sha256 = @computed_hashes[font.label]
+        end
+        atomic_write(@manifest_path, manifest.to_yaml)
+      end
+
+      def atomic_write(path, content)
+        tmp = path.dirname.join("#{path.basename}.tmp")
+        tmp.write(content)
+        File.rename(tmp.to_s, path.to_s)
+      end
+    end
+  end
+end

data/lib/ucode/fetch.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
 module Ucode
-  # Fetchers — download UCD.zip, Unihan.zip, and per-block Code Charts PDFs.
+  # Fetchers — download UCD.zip, Unihan.zip, per-block Code Charts
+  # PDFs, and the specialist Tier 1 fonts that fontist's formula
+  # index does not carry.
   #
-  # OCP: Http is the single network boundary. New source types add a new
-  # Fetcher class that calls Http.get; no new HTTP stack.
+  # OCP: Http is the single network boundary. New source types add a
+  # new Fetcher class that calls Http.get; no new HTTP stack.
   module Fetch
     autoload :Http, "ucode/fetch/http"
     autoload :UcdZip, "ucode/fetch/ucd_zip"
     autoload :UnihanZip, "ucode/fetch/unihan_zip"
     autoload :CodeCharts, "ucode/fetch/code_charts"
+    autoload :FontFetcher, "ucode/fetch/font_fetcher"
+    autoload :SpecialistFontFetcher, "ucode/fetch/specialist_font_fetcher"
   end
 end

data/lib/ucode/glyphs/real_fonts/cmap_cache.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "fontisan"
+
+require "ucode/glyphs/real_fonts/font_locator"
+require "ucode/models/glyph_source"
+
+module Ucode
+  module Glyphs
+    module RealFonts
+      # Lazily loads each Tier 1 font's cmap and answers per-codepoint
+      # coverage queries. Used by {SourceConfig::CoverageAssertion}
+      # to walk every assigned codepoint without re-parsing the same
+      # font once per block.
+      #
+      # One font load per unique label. The cache key is the source's
+      # `label` (fontist formula name or `name=path` short name) —
+      # if two blocks reference the same label, the cmap loads once.
+      #
+      # Fonts that cannot be located or parsed produce an empty set;
+      # {CoverageAssertion} records every assigned codepoint in those
+      # blocks as a gap. Missing fonts are themselves curation
+      # findings — the walker surfaces them rather than hiding them
+      # behind an exception.
+      class CmapCache
+        # @param font_locator [FontLocator] injectable for testing.
+        #   Defaults to a fresh instance with `install: false`
+        #   semantics (we never auto-install during a coverage walk;
+        #   that's a separate operation).
+        def initialize(font_locator: FontLocator.new)
+          @font_locator = font_locator
+          @cmaps = {}
+        end
+
+        # @param source [Ucode::Models::GlyphSource]
+        # @param codepoint [Integer]
+        # @return [Boolean] true when the source's cmap includes the
+        #   codepoint. False when the font is missing, fails to load,
+        #   or doesn't have an outline for that codepoint.
+        def covers?(source, codepoint)
+          cmap_for(source).include?(codepoint)
+        end
+
+        private
+
+        def cmap_for(source)
+          @cmaps[source.label] ||= load_cmap(source)
+        end
+
+        def load_cmap(source)
+          path = resolve_path(source)
+          return Set.new unless path
+
+          font = Fontisan::FontLoader.load(path.to_s)
+          cmap = font.table(Fontisan::Constants::CMAP_TAG)
+          return Set.new unless cmap
+
+          cmap.unicode_mappings.keys.to_set
+        rescue StandardError
+          Set.new
+        end
+
+        def resolve_path(source)
+          result = @font_locator.locate(source.to_font_spec, install: false)
+          result&.path
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/real_fonts.rb

@@ -26,6 +26,7 @@ module Ucode
                "ucode/glyphs/real_fonts/font_coverage_report"
       autoload :FontLocator, "ucode/glyphs/real_fonts/font_locator"
       autoload :CoverageAuditor, "ucode/glyphs/real_fonts/coverage_auditor"
+      autoload :CmapCache, "ucode/glyphs/real_fonts/cmap_cache"
       autoload :Writer, "ucode/glyphs/real_fonts/writer"
     end
   end