ucode 0.1.0

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "fontist"
+
+module Ucode
+  module Glyphs
+    module RealFonts
+      # Resolves a user-provided font specifier to a concrete file
+      # path on disk. Resolution order:
+      #
+      #   1. Direct file path — returns it if it exists. Useful for
+      #      local checkouts (e.g. a developer's clone of Lentariso).
+      #   2. `Fontist::Font.find(name)` — returns the already-installed
+      #      font path if fontist has it on disk.
+      #   3. `Fontist::Font.install(name)` — downloads + installs the
+      #      font via the fontist formula index.
+      #
+      # Fontist is the canonical discovery layer for the fontist
+      # ecosystem. We never reach into other package managers or
+      # hardcode URLs here — formulas live in fontist/formulas.
+      class FontLocator
+        LocateResult = Struct.new(:name, :path, :via, keyword_init: true)
+
+        # @param spec [String] either a file path or a fontist formula
+        #   name (case-insensitive). A `name=path` form is also
+        #   accepted so a CLI can name the font whatever the user
+        #   wants without depending on the formula's family name.
+        # @param install [Boolean] if true and the font is not on
+        #   disk, attempt `Fontist::Font.install`. Default: true.
+        # @return [LocateResult]
+        # @raise [Errno::ENOENT] if path does not exist and fontist
+        #   cannot resolve the name.
+        def locate(spec, install: true)
+          name, path = split_spec(spec)
+          return result(name, path, :direct) if path && File.exist?(path)
+
+          via_fontist = find_via_fontist(name, install: install)
+          return via_fontist if via_fontist
+
+          raise Errno::ENOENT, "Font not found: #{spec}"
+        end
+
+        private
+
+        def split_spec(spec)
+          if spec.include?("=")
+            name, path = spec.split("=", 2)
+            [name.strip, path]
+          else
+            [spec, spec]
+          end
+        end
+
+        def find_via_fontist(name, install:)
+          found = safe_fontist_lookup { Fontist::Font.find(name) }
+          return result(name, found, :fontist_find) if found
+          return nil unless install
+
+          paths = install_via_fontist(name)
+          return nil unless paths&.any?
+
+          result(name, paths.first, :fontist_install)
+        end
+
+        def install_via_fontist(name)
+          Fontist::Font.install(
+            name,
+            confirmation: "yes",
+            hide_licenses: true,
+          )
+        rescue Fontist::Errors::UnsupportedFontError,
+               Fontist::Errors::FontNotFoundError
+          nil
+        end
+
+        # `Fontist::Font.find` raises `UnsupportedFontError` when the
+        # name isn't in the formula index — that's a "not found"
+        # outcome for our purposes, not an exceptional control-flow
+        # event. Translate to nil so the caller can fall through to
+        # the install-or-fail branch.
+        def safe_fontist_lookup
+          yield
+        rescue Fontist::Errors::UnsupportedFontError, Fontist::Errors::FontNotFoundError
+          nil
+        end
+
+        def result(name, path, via)
+          LocateResult.new(name: name, path: Pathname(path), via: via)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Glyphs
+    module RealFonts
+      # The new blocks introduced by Unicode 17.0 that this audit
+      # cares about. Each block carries its explicit assigned-codepoint
+      # ranges.
+      #
+      # Sources (in priority order):
+      #   1. Unicode 17.0 `Blocks.txt` — block name + first/last cp.
+      #   2. Per-block code-chart legend on unicode.org — published
+      #      assigned-codepoint count.
+      #   3. Direct inspection of a known-good font (fontisan audit)
+      #      — confirms at least the assigned count when a font has
+      #      100% coverage.
+      #
+      # Where the chart legend publishes an assigned count but not the
+      # exact ranges, we approximate by extending from the block's
+      # first codepoint up to the count. This may mis-attribute a few
+      # reserved slots in the middle of a block as "assigned"; the
+      # `missing_cps` list then over-reports by those slots. Refining
+      # to exact ranges is a follow-up once UCD 17.0 text files are
+      # integrated into the ucode dataset.
+      #
+      # Block names match the verbatim UCD block name (`Blocks.txt`
+      # field 2) — never slugified.
+      Block = Struct.new(:name, :first_cp, :last_cp, :assigned_ranges,
+                         keyword_init: true) do
+        def covers?(codepoint)
+          codepoint.between?(first_cp, last_cp)
+        end
+      end
+
+      module Unicode17Blocks
+        ALL = [
+          # Sidetic — U+10940..U+1095F, 26 assigned (verified via
+          # Lentariso: covers U+10940..U+10959 exactly).
+          Block.new(name: "Sidetic",
+                    first_cp: 0x10940, last_cp: 0x1095F,
+                    assigned_ranges: [0x10940..0x10959]),
+          # Sharada Supplement — U+11B60..U+11B7F, 8 assigned.
+          Block.new(name: "Sharada Supplement",
+                    first_cp: 0x11B60, last_cp: 0x11B7F,
+                    assigned_ranges: [0x11B60..0x11B67]),
+          # Tolong Siki — U+11DB0..U+11DEF, 54 assigned (letters +
+          # digits; ranges approximate).
+          Block.new(name: "Tolong Siki",
+                    first_cp: 0x11DB0, last_cp: 0x11DEF,
+                    assigned_ranges: [0x11DB0..0x11DE5]),
+          # Beria Erfe — U+16EA0..U+16EDF, 50 assigned across two runs
+          # (U+16EB9-U+16EBA reserved — verified via Kedebideri).
+          Block.new(name: "Beria Erfe",
+                    first_cp: 0x16EA0, last_cp: 0x16EDF,
+                    assigned_ranges: [0x16EA0..0x16EB8, 0x16EBB..0x16ED3]),
+          # Tai Yo — full block range; published as 52 codepoints in
+          # the UCD 17.0 block list.
+          Block.new(name: "Tai Yo",
+                    first_cp: 0x1E6C0, last_cp: 0x1E6F3,
+                    assigned_ranges: [0x1E6C0..0x1E6F3]),
+          # Symbols for Legacy Computing Supplement — 9 assigned
+          # (approximate; U+1CC00..U+1CC08).
+          Block.new(name: "Symbols for Legacy Computing Supplement",
+                    first_cp: 0x1CC00, last_cp: 0x1CCFF,
+                    assigned_ranges: [0x1CC00..0x1CC08]),
+          # Supplemental Arrows-C — 9 assigned (U+1CF00..U+1CF08).
+          Block.new(name: "Supplemental Arrows-C",
+                    first_cp: 0x1CF00, last_cp: 0x1CFCF,
+                    assigned_ranges: [0x1CF00..0x1CF08]),
+          # Alchemical Symbols — 4 new in Unicode 17.
+          Block.new(name: "Alchemical Symbols",
+                    first_cp: 0x1F740, last_cp: 0x1F77F,
+                    assigned_ranges: [0x1F740..0x1F743]),
+          # Miscellaneous Symbols Supplement — published as 34
+          # assigned in Unicode 17; ranges approximate.
+          Block.new(name: "Miscellaneous Symbols Supplement",
+                    first_cp: 0x1FA70, last_cp: 0x1FAFF,
+                    assigned_ranges: [0x1FA70..0x1FA91]),
+          # Musical Symbols Supplement (Znamenny Notation additions)
+          # — U+1D200..U+1D24F, additions in Unicode 17. Range
+          # approximate.
+          Block.new(name: "Musical Symbols Supplement",
+                    first_cp: 0x1D200, last_cp: 0x1D24F,
+                    assigned_ranges: [0x1D200..0x1D245]),
+          # CJK Unified Ideographs Extension J — U+31350..U+323AF,
+          # 4,293 assigned per UCD 17.0. Audit uses the published
+          # block range; the assigned set may extend slightly past
+          # U+323AF in some distributions.
+          Block.new(name: "CJK Unified Ideographs Extension J",
+                    first_cp: 0x31350, last_cp: 0x323AF,
+                    assigned_ranges: [0x31350..0x323AF]),
+        ].freeze
+
+        def self.each(&)
+          ALL.each(&)
+        end
+
+        def self.for_codepoint(codepoint)
+          ALL.find { |b| codepoint >= b.first_cp && codepoint <= b.last_cp }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+require_relative "font_coverage_report"
+
+module Ucode
+  module Glyphs
+    module RealFonts
+      # Persists a {FontCoverageReport} as a JSON file under
+      # `output/font_coverage/`. One file per audited face; the
+      # filename is derived from the report's `source_file` so the
+      # source and the report are trivially correlated.
+      class Writer
+        DEFAULT_OUTPUT_DIR = "font_coverage"
+
+        # @param output_root [Pathname, String] parent directory; the
+        #   `font_coverage/` subdirectory is created inside it.
+        def initialize(output_root)
+          @output_root = Pathname(output_root)
+        end
+
+        # @param report [FontCoverageReport]
+        # @return [Pathname] absolute path of the written file
+        def write(report)
+          path = target_path(report)
+          path.dirname.mkpath
+          path.write("#{JSON.pretty_generate(report.to_hash)}\n")
+          path
+        end
+
+        private
+
+        def target_path(report)
+          base = safe_basename(source_label(report))
+          @output_root.join(DEFAULT_OUTPUT_DIR, "#{base}.json")
+        end
+
+        def source_label(report)
+          report.source_file || report.postscript_name || "font"
+        end
+
+        def safe_basename(name)
+          File.basename(name, ".*").gsub(/[^A-Za-z0-9._-]/, "_")
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/real_fonts.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Glyphs
+    # Tier-1 glyph sourcing — real font cmaps.
+    #
+    # When a real OpenType/TrueType font covers a Unicode 17 block,
+    # walking its cmap and lifting glyph outlines directly from the
+    # font's `glyf`/`CFF ` table produces higher-fidelity SVGs than
+    # vector-extracting from the Code Charts PDF (which composites
+    # chart-grid chrome into the same glyph). Tier 1 is the preferred
+    # source; Code Charts PDF (pillar 1 ToUnicode, pillar 2 positional
+    # correlation, pillar 3 Last Resort) are fallbacks for codepoints
+    # no real font covers.
+    #
+    # Font discovery goes through **fontist** (`Fontist::Font.find` /
+    # `install`); font parsing/audit/outline extraction goes through
+    # **fontisan** (`Fontisan::Commands::AuditCommand`,
+    # `Fontisan::OutlineExtractor`). Both gems live in the fontist
+    # org; fontist already depends on fontisan. No other Ruby
+    # font-parsing library is permitted.
+    module RealFonts
+      autoload :Unicode17Blocks, "ucode/glyphs/real_fonts/unicode_17_blocks"
+      autoload :BlockCoverage, "ucode/glyphs/real_fonts/block_coverage"
+      autoload :FontCoverageReport,
+               "ucode/glyphs/real_fonts/font_coverage_report"
+      autoload :FontLocator, "ucode/glyphs/real_fonts/font_locator"
+      autoload :CoverageAuditor, "ucode/glyphs/real_fonts/coverage_auditor"
+      autoload :Writer, "ucode/glyphs/real_fonts/writer"
+    end
+  end
+end

data/lib/ucode/glyphs/writer.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "thread"
+require "tmpdir"
+require "nokogiri"
+
+require "ucode/error"
+require "ucode/glyphs/page_renderer"
+require "ucode/glyphs/grid_detector"
+require "ucode/glyphs/cell_extractor"
+require "ucode/repo/atomic_writes"
+require "ucode/repo/paths"
+
+module Ucode
+  module Glyphs
+    # Writes `glyph.svg` for every codepoint in a block by orchestrating
+    # the per-block pipeline: render PDF page → detect grid → extract
+    # each cell → write atomic file.
+    #
+    # The Writer is **page-driven**: the caller hands it a `page_map`
+    # (`{ page_num => first_cp_on_that_page }`) so the writer knows what
+    # codepoint each detected cell anchor corresponds to. This is the
+    # one piece of state the Writer can't derive on its own — pdftocairo
+    # converts the row's codepoint labels to outlined glyphs, so they
+    # aren't readable as text.
+    #
+    # **Idempotent**: re-runs are no-ops via `Repo::AtomicWrites` (byte
+    # comparison; same content is skipped). Safe to re-run on the whole
+    # output tree.
+    #
+    # **Atomic**: writes go through `<path>.tmp` + rename. A crash mid-
+    # write leaves either the old file or no file, never a truncated one.
+    #
+    # **Placeholder for assigned codepoints with no glyph**: when a
+    # codepoint is listed in `block.codepoint_ids` but no cell is found
+    # on any rendered page, a small placeholder SVG is written so the
+    # site can render a "no official glyph" badge. Counted in the tally
+    # as `placeholder`.
+    #
+    # **Pure-ish**: takes a renderer instance (defaults to the first
+    # available system renderer) and a fetcher; both are injectable for
+    # tests. The only I/O is the renderer, the writer's output_root, and
+    # any optional cache.
+    class Writer
+      include Repo::AtomicWrites
+
+      PlaceholderViewBoxSize = 100
+      private_constant :PlaceholderViewBoxSize
+
+      # @param output_root [String, Pathname]
+      # @param renderer [Ucode::Glyphs::PageRenderer] concrete renderer class
+      # @param parallel_workers [Integer] worker pool size for #write_all
+      def initialize(output_root:, renderer: PageRenderer.default, parallel_workers: 4)
+        @output_root = Pathname.new(output_root)
+        @renderer = renderer
+        @parallel_workers = parallel_workers
+      end
+
+      # Process every page in `page_map`, writing glyph.svg for each
+      # codepoint that (a) falls inside the block's range and (b) has a
+      # detectable glyph on the page.
+      #
+      # @param block [Ucode::Models::Block]
+      # @param pdf_path [String, Pathname]
+      # @param page_map [Hash{Integer => Integer}] page_num => first cp on that page
+      # @param strict [Boolean] raise GlyphError when the PDF is missing
+      #   or no grid is detected on any page; when false, returns a tally
+      #   with `no_grid` set and writes placeholders for assigned cps.
+      # @return [Hash] tally { written: N, skipped: N, empty: N,
+      #   placeholder: N, no_grid: N }
+      def write_block(block:, pdf_path:, page_map:, strict: false)
+        unless pdf_path && Pathname.new(pdf_path).exist?
+          raise_missing_pdf!(block, pdf_path) if strict
+          return placeholder_pass(block, zero_tally.tap { |h| h[:no_grid] = 1 })
+        end
+
+        tally = zero_tally
+        page_map.each do |page_num, first_cp|
+          merge_tally!(tally, write_page(block: block, pdf_path: pdf_path,
+                                          page_num: page_num, first_cp: first_cp))
+        end
+        placeholder_pass(block, tally)
+      end
+
+      # Render one page, detect its grid, write every cell whose codepoint
+      # falls inside `block`'s range.
+      #
+      # @param block [Ucode::Models::Block]
+      # @param pdf_path [String, Pathname]
+      # @param page_num [Integer] 1-based PDF page number
+      # @param first_cp [Integer] codepoint of the grid's top-left cell
+      # @return [Hash] tally
+      def write_page(block:, pdf_path:, page_num:, first_cp:)
+        svg_doc = render_page(pdf_path, page_num)
+        return no_grid_tally unless svg_doc
+
+        grid = GridDetector.detect(svg_doc, block_first_cp: first_cp)
+        return no_grid_tally unless grid
+
+        counts = zero_tally
+        extractor = CellExtractor.new(svg_doc)
+        grid.rows.times do |row|
+          grid.columns.times do |col|
+            cp = grid.codepoint_at(row, col)
+            next unless cp && block.covers?(cp)
+
+            cell_svg = extractor.extract(grid, cp)
+            if cell_svg.nil?
+              counts[:empty] += 1
+              next
+            end
+
+            written = write_glyph(block, cp, cell_svg)
+            counts[written ? :written : :skipped] += 1
+          end
+        end
+        counts
+      end
+
+      # Drain a list of block-spec hashes through the worker pool.
+      # Each spec has the same shape as #write_block's kwargs:
+      #
+      #   { block:, pdf_path:, page_map: }
+      #
+      # @param specs [Array<Hash>]
+      # @return [Hash] aggregated tally across all blocks
+      def write_all(specs)
+        return drain_inline(specs) if @parallel_workers <= 1
+
+        drain_threaded(specs)
+      end
+
+      private
+
+      def zero_tally
+        { written: 0, skipped: 0, empty: 0, placeholder: 0, no_grid: 0 }
+      end
+
+      def no_grid_tally
+        zero_tally.tap { |h| h[:no_grid] = 1 }
+      end
+
+      def merge_tally!(acc, other)
+        other.each { |k, v| acc[k] = (acc[k] || 0) + v }
+      end
+
+      def drain_inline(specs)
+        specs.each_with_object(zero_tally) do |spec, tally|
+          merge_tally!(tally, write_block(**spec))
+        end
+      end
+
+      def drain_threaded(specs)
+        queue = Queue.new
+        mutex = Mutex.new
+        tally = zero_tally
+
+        workers = Array.new(@parallel_workers) do
+          Thread.new do
+            loop do
+              spec = queue.pop
+              break if spec.nil?
+
+              result = write_block(**spec)
+              mutex.synchronize { merge_tally!(tally, result) }
+            end
+          end
+        end
+
+        specs.each { |spec| queue << spec }
+        @parallel_workers.times { queue << nil }
+        workers.each(&:join)
+        tally
+      end
+
+      def render_page(pdf_path, page_num)
+        Dir.mktmpdir do |dir|
+          out = File.join(dir, "p#{page_num}.svg")
+          begin
+            result = @renderer.render(Pathname.new(pdf_path), page_num, out)
+          rescue Ucode::PdfRenderError
+            # Graceful degradation: a broken renderer (e.g. mutool on a
+            # host without LCMS) yields no_grid → placeholders downstream.
+            next nil
+          end
+          return nil unless result == :ok && File.exist?(out)
+
+          Nokogiri::XML(File.read(out))
+        end
+      end
+
+      def write_glyph(block, codepoint, cell_svg)
+        cp_id = Repo::Paths.cp_id(codepoint)
+        path = Repo::Paths.codepoint_glyph_path(@output_root, block.id, cp_id)
+        write_atomic(path, serialize_svg(cell_svg))
+      end
+
+      # For every assigned codepoint in the block that doesn't already
+      # have a glyph.svg on disk, write a placeholder.
+      def placeholder_pass(block, tally)
+        return tally if block.codepoint_ids.nil? || block.codepoint_ids.empty?
+
+        block.codepoint_ids.each do |cp_id|
+          cp = cp_id_to_int(cp_id)
+          next unless cp
+          next unless block.covers?(cp)
+
+          path = Repo::Paths.codepoint_glyph_path(@output_root, block.id, cp_id)
+          next if path.exist?
+
+          if write_atomic(path, placeholder_svg_payload)
+            tally[:placeholder] = (tally[:placeholder] || 0) + 1
+          end
+        end
+        tally
+      end
+
+      def cp_id_to_int(cp_id)
+        return nil unless cp_id.is_a?(String) && cp_id.start_with?("U+")
+
+        cp_id[2..].to_i(16)
+      end
+
+      def placeholder_svg_payload
+        size = PlaceholderViewBoxSize
+        # A simple dashed square + text marker so the site can render
+        # an obvious "no official glyph" badge without needing extra state.
+        <<~SVG
+          <?xml version="1.0" encoding="UTF-8"?>
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 #{size} #{size}" width="#{size}" height="#{size}">
+            <rect x="1" y="1" width="#{size - 2}" height="#{size - 2}" fill="none" stroke="#999" stroke-width="1" stroke-dasharray="4 4"/>
+            <text x="#{size / 2}" y="#{size / 2}" font-family="sans-serif" font-size="14" text-anchor="middle" dominant-baseline="middle" fill="#999">no glyph</text>
+          </svg>
+        SVG
+      end
+
+      def serialize_svg(doc)
+        doc.to_xml.strip
+      end
+
+      def raise_missing_pdf!(block, pdf_path)
+        raise Ucode::GlyphError.new(
+          "no PDF available for block '#{block.id}'",
+          context: { block_id: block.id, pdf_path: pdf_path&.to_s },
+        )
+      end
+    end
+  end
+end

data/lib/ucode/glyphs.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Ucode
+  # Glyphs — converts Code Charts PDF pages into per-codepoint SVGs.
+  #
+  # Pipeline: fetch per-block PDF → render to SVG → detect grid → extract
+  # cell → normalize viewBox → write glyph.svg.
+  #
+  # Vector extraction only. NEVER run OCR.
+  module Glyphs
+    autoload :PdfFetcher, "ucode/glyphs/pdf_fetcher"
+    autoload :PageRenderer, "ucode/glyphs/page_renderer"
+    autoload :MutoolRenderer, "ucode/glyphs/mutool_renderer"
+    autoload :Pdf2svgRenderer, "ucode/glyphs/pdf2svg_renderer"
+    autoload :DvisvgmRenderer, "ucode/glyphs/dvisvgm_renderer"
+    autoload :PdftocairoRenderer, "ucode/glyphs/pdftocairo_renderer"
+    autoload :Grid, "ucode/glyphs/grid"
+    autoload :PathBbox, "ucode/glyphs/path_bbox"
+    autoload :GridDetector, "ucode/glyphs/grid_detector"
+    autoload :CellExtractor, "ucode/glyphs/cell_extractor"
+    autoload :MonolithPageMap, "ucode/glyphs/monolith_page_map"
+    autoload :Writer, "ucode/glyphs/writer"
+    autoload :LastResort, "ucode/glyphs/last_resort"
+    autoload :EmbeddedFonts, "ucode/glyphs/embedded_fonts"
+    autoload :RealFonts, "ucode/glyphs/real_fonts"
+  end
+end

data/lib/ucode/index.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "yaml"
+
+module Ucode
+  # Sorted, run-length-encoded lookup table over Unicode codepoints.
+  #
+  # One Index answers "what <thing> does codepoint N belong to?" for one
+  # property (block, or script). Lookup is O(log N) via `bsearch_index`.
+  #
+  # Two ways to construct:
+  #   - `Index.from_triples([[first, last, name], ...])`
+  #   - `Index.load(path)` from a YAML file previously written by `#save`.
+  #
+  # The YAML form is the dependency-free alternative to SQLite — same
+  # query API, simpler ops. Pick whichever fits the deployment.
+  class Index
+    include Enumerable
+
+    def initialize(entries)
+      @entries = entries.sort
+    end
+
+    attr_reader :entries
+
+    def each(&block)
+      @entries.each(&block)
+    end
+
+    def size
+      @entries.size
+    end
+
+    # @param codepoint [Integer]
+    # @return [String, nil] the name of the range covering `codepoint`, or nil
+    def lookup(codepoint)
+      idx = bsearch_index(codepoint)
+      idx && @entries[idx].name
+    end
+
+    # Enumerate every range whose [first_cp, last_cp] overlaps the
+    # inclusive query range. Returns a lazy Enumerator when called
+    # without a block.
+    # @param first [Integer]
+    # @param last [Integer]
+    # @return [Enumerator<RangeEntry>, nil]
+    def each_overlapping(first, last, &block)
+      return enum_for(:each_overlapping, first, last) unless block_given?
+
+      start_idx = bsearch_first_overlap(first)
+      return if start_idx.nil?
+
+      @entries[start_idx..].each do |entry|
+        break if entry.first_cp > last
+
+        yield entry if entry.last_cp >= first
+      end
+    end
+
+    # Serialize to a YAML file.
+    # @param path [String, Pathname]
+    # @return [void]
+    def save(path)
+      File.open(path, "w") do |file|
+        YAML.dump(@entries.map(&:to_h), file)
+      end
+    end
+
+    # Load from a YAML file previously written by #save.
+    # @param path [String, Pathname]
+    # @return [Index]
+    def self.load(path)
+      hashes = YAML.load_file(path)
+      new(hashes.map { |h| RangeEntry.from_h(h) })
+    end
+
+    # Build an Index from raw [first_cp, last_cp, name] triples.
+    # @param triples [Array<Array(Integer, Integer, String)>]
+    # @return [Index]
+    def self.from_triples(triples)
+      new(triples.map { |first, last, name| RangeEntry.new(first, last, name) })
+    end
+
+    private
+
+    # bsearch_index integer-mode convention: -1 = search LEFT, +1 = RIGHT,
+    # 0 = match. See Coordinator#find_in_range for the same convention.
+    def bsearch_index(codepoint)
+      @entries.bsearch_index do |entry|
+        if codepoint < entry.first_cp
+          -1
+        elsif codepoint > entry.last_cp
+          1
+        else
+          0
+        end
+      end
+    end
+
+    # Boolean-mode bsearch: first entry whose `last_cp >= first`.
+    def bsearch_first_overlap(first)
+      @entries.bsearch_index { |entry| entry.last_cp >= first }
+    end
+  end
+end