ucode 0.1.0

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "tempfile"
+
+require "fontisan"
+require_relative "../../error"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Value object describing one Type0 font discovered in the Code
+      # Charts PDF, plus lazy accessors for its outline data.
+      #
+      # A FontEntry is constructed by {Catalog} during the PDF walk and
+      # is the unit of work for the renderer. Each entry owns:
+      #
+      #   * identity — `base_font` name, font dict object number
+      #   * stream refs — object numbers of the FontDescriptor's
+      #     FontFile2 (TrueType) / FontFile3 (CFF) and the ToUnicode CMap
+      #   * `cid_to_gid_map` — `:identity` (gid == cid) or `:stream`
+      #     (we'd need to parse a separate map; not currently supported)
+      #   * `codepoint_to_gid` — the per-font map built from the parsed
+      #     ToUnicode CMap. Frozen.
+      #
+      # The fontisan accessor is built lazily on first {#accessor} call,
+      # and the font program is extracted to the {Source} cache directory
+      # at the same point. Subsequent calls reuse the cached file unless
+      # the PDF is newer than the cache.
+      class FontEntry
+        attr_reader :base_font, :font_obj_id, :fontfile_obj_id,
+                    :fontfile_kind, :tounicode_obj_id, :cid_to_gid_map,
+                    :codepoint_to_gid, :source
+
+        # @param base_font [String] e.g. "CIAIIP+Uni2000Generalpunctuation"
+        # @param font_obj_id [Integer] Type0 font dict object number
+        # @param fontfile_obj_id [Integer] FontFile2/3 stream object number
+        # @param fontfile_kind [Symbol] :ttf (FontFile2) or :cff (FontFile3)
+        # @param tounicode_obj_id [Integer] ToUnicode CMap stream object number
+        # @param cid_to_gid_map [Symbol] :identity (we only support this)
+        # @param codepoint_to_gid [Hash{Integer=>Integer}] frozen cp → gid
+        # @param source [Source] for cache path + pdf path
+        def initialize(base_font:, font_obj_id:, fontfile_obj_id:,
+                       fontfile_kind:, tounicode_obj_id:, cid_to_gid_map:,
+                       codepoint_to_gid:, source:)
+          @base_font = base_font
+          @font_obj_id = font_obj_id
+          @fontfile_obj_id = fontfile_obj_id
+          @fontfile_kind = fontfile_kind
+          @tounicode_obj_id = tounicode_obj_id
+          @cid_to_gid_map = cid_to_gid_map
+          @codepoint_to_gid = codepoint_to_gid
+          @source = source
+          @accessor = nil
+        end
+
+        # @param codepoint [Integer]
+        # @return [Integer, nil] GID for the codepoint in this font, or
+        #   nil if the codepoint isn't covered
+        def gid_for(codepoint)
+          @codepoint_to_gid[codepoint]
+        end
+
+        # @return [Array<Integer>] codepoints covered by this font
+        def codepoints
+          @codepoint_to_gid.keys
+        end
+
+        # @return [String] ".ttf" or ".cff" — cache file extension
+        def fontfile_extension
+          @fontfile_kind == :ttf ? ".ttf" : ".cff"
+        end
+
+        # @return [Pathname] where the extracted font stream is cached
+        def cache_path
+          @source.font_cache_path(@base_font, fontfile_extension)
+        end
+
+        # Lazy: extracts the font program to the cache (if missing or
+        # stale) and loads it via fontisan. Memoized per FontEntry.
+        #
+        # @return [Fontisan::GlyphAccessor]
+        def accessor
+          @accessor ||= build_accessor
+        end
+
+        # Force-clear the cached accessor and fontisan state. Useful in
+        # long-running processes that walk many fonts.
+        #
+        # @return [void]
+        def reset_accessor!
+          @accessor = nil
+        end
+
+        private
+
+        def build_accessor
+          ensure_font_cached!
+          font = Fontisan::FontLoader.load(cache_path.to_s)
+          Fontisan::GlyphAccessor.new(font)
+        end
+
+        def ensure_font_cached!
+          return if cache_path.exist? && cache_path.mtime >= @source.pdf_path.mtime
+
+          cache_path.dirname.mkpath unless cache_path.dirname.exist?
+          extract_font_stream!
+        end
+
+        def extract_font_stream!
+          Tempfile.create([@base_font, fontfile_extension], cache_path.dirname.to_s, binmode: true) do |tmp|
+            tmp.close
+            ok = system("mutool", "show", "-o", tmp.path, "-b",
+                        @source.pdf_to_s, @fontfile_obj_id.to_s,
+                        out: File::NULL, err: File::NULL)
+            raise Ucode::EmbeddedFontsMissingError,
+                  "mutool failed to extract font stream (obj=#{@fontfile_obj_id})" unless ok
+
+            FileUtils.mv(tmp.path, cache_path.to_s, force: true)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "svg"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Renders one codepoint's glyph by chaining the {Catalog} index
+      # lookup → {FontEntry} accessor → {Svg} wrapper.
+      #
+      # Mirrors {LastResort::Renderer}: a Result struct is returned on
+      # success, nil on miss. The caller (Writer or CLI) decides how to
+      # handle misses — typically by falling back to the LastResort
+      # renderer.
+      class Renderer
+        # Result of rendering one codepoint.
+        Result = Struct.new(:codepoint, :base_font, :gid, :svg, keyword_init: true) do
+          def ok?
+            !svg.nil?
+          end
+        end
+
+        # @param catalog [Catalog]
+        def initialize(catalog)
+          @catalog = catalog
+        end
+
+        # @param codepoint [Integer]
+        # @return [Result, nil] nil when no font in the PDF covers this
+        #   codepoint, or when the GID's outline is empty
+        def render(codepoint)
+          entry = @catalog.lookup(codepoint)
+          return nil unless entry
+
+          gid = entry.gid_for(codepoint)
+          return nil unless gid
+
+          outline = entry.accessor.outline_for_id(gid)
+          return nil if outline.nil? || outline.empty?
+
+          svg = Svg.new(outline, codepoint: codepoint, base_font: entry.base_font).to_s
+          Result.new(codepoint: codepoint, base_font: entry.base_font, gid: gid, svg: svg)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "../../error"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Locates the Code Charts PDF on disk and the directory where
+      # extracted font streams are cached.
+      #
+      # PDF resolution order (first match wins):
+      #
+      #   1. Explicit `pdf:` argument.
+      #   2. `UCODE_CODE_CHARTS_PDF` environment variable.
+      #   3. Conventional `<gem_root>/CodeCharts.pdf`.
+      #
+      # Per-block PDFs (preferred for incremental runs) can be supplied
+      # via the `pdf:` argument by the caller — typically the CLI.
+      #
+      # Cache resolution order:
+      #
+      #   1. Explicit `cache_dir:` argument.
+      #   2. `UCODE_PDF_FONT_CACHE` environment variable.
+      #   3. Conventional `<gem_root>/data/pdf-fonts/`.
+      #
+      # The cache holds one file per embedded font program, named after
+      # the BaseFont (e.g. `CIAIIP+Uni2000Generalpunctuation.ttf`).
+      # Re-runs skip extraction when the cached file is newer than the
+      # PDF.
+      class Source
+        attr_reader :pdf_path, :cache_dir
+
+        # @param pdf [String, Pathname, nil] path to a Code Charts PDF
+        # @param cache_dir [String, Pathname, nil] directory for cached
+        #   font files; created on demand
+        # @param env [Hash{String=>String}] env var source (defaults to ENV)
+        # @param gem_root [String, Pathname, nil] gem root for the
+        #   conventional fallback; injectable for tests
+        # @raise [Ucode::EmbeddedFontsMissingError] if the PDF is missing
+        def initialize(pdf: nil, cache_dir: nil, env: ENV, gem_root: nil)
+          @pdf_path = resolve_pdf(pdf, env, gem_root)
+          raise Ucode::EmbeddedFontsMissingError,
+                "Code Charts PDF not found at #{@pdf_path}" unless @pdf_path&.exist?
+
+          @cache_dir = resolve_cache(cache_dir, env, gem_root)
+          @cache_dir.mkpath unless @cache_dir.exist?
+        end
+
+        # @return [String] absolute path to the PDF, suitable for shelling
+        #   out to `mutool`
+        def pdf_to_s
+          @pdf_path.to_s
+        end
+
+        # @param base_font [String] e.g. "CIAIIP+Uni2000Generalpunctuation"
+        # @param extension [String] e.g. ".ttf" or ".cff"
+        # @return [Pathname] cache path for the named font
+        def font_cache_path(base_font, extension)
+          @cache_dir.join("#{base_font}#{extension}")
+        end
+
+        private
+
+        def resolve_pdf(explicit, env, gem_root)
+          return Pathname.new(explicit).expand_path if explicit
+
+          env_val = env["UCODE_CODE_CHARTS_PDF"]
+          return Pathname.new(env_val).expand_path if env_val && !env_val.empty?
+
+          base = gem_root ? Pathname.new(gem_root) : default_gem_root
+          base.expand_path.join("CodeCharts.pdf")
+        end
+
+        def resolve_cache(explicit, env, gem_root)
+          return Pathname.new(explicit).expand_path if explicit
+
+          env_val = env["UCODE_PDF_FONT_CACHE"]
+          return Pathname.new(env_val).expand_path if env_val && !env_val.empty?
+
+          base = gem_root ? Pathname.new(gem_root) : default_gem_root
+          base.expand_path.join("data", "pdf-fonts")
+        end
+
+        # __dir__ = lib/ucode/glyphs/embedded_fonts/. Five `..` get us
+        # back to the project root (the directory containing `lib/`).
+        def default_gem_root
+          Pathname.new(__dir__).join("..", "..", "..", "..", "..")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Converts a fontisan `GlyphOutline` into a standalone SVG document
+      # shaped to match the {LastResort::Svg} output (y-flipped, viewBox
+      # padded around the bbox, single `<path>` child).
+      #
+      # The fontisan outline is in font units, with y growing upward
+      # (PostScript convention). SVG y grows downward. We:
+      #
+      #   1. Walk `outline.to_commands` and re-emit each command with
+      #      the y coordinate negated. The commands we get are
+      #      `:move_to`, `:line_to`, `:curve_to` (quadratic; one
+      #      control + one end point), and `:close_path`.
+      #   2. Build a viewBox from the outline's bbox with a small pad,
+      #      y-flipped so min_y is the SVG-space top.
+      #
+      # The y-negation happens at emit time, not at parse time, so we
+      # never have to read back a serialized path string.
+      class Svg
+        PaddingRatio = 0.08
+        private_constant :PaddingRatio
+
+        # @param outline [Fontisan::Models::GlyphOutline]
+        # @param codepoint [Integer, nil] optional, for the `<title>`
+        # @param base_font [String, nil] optional source-font name, also
+        #   for the `<title>` (debugging which PDF font a glyph came from)
+        def initialize(outline, codepoint: nil, base_font: nil)
+          @outline = outline
+          @codepoint = codepoint
+          @base_font = base_font
+        end
+
+        # @return [String] complete `<svg>...</svg>` document
+        def to_s
+          box = view_box
+          lines = []
+          lines << %(<svg xmlns="http://www.w3.org/2000/svg" viewBox="#{format_dims(box)}" width="#{format_num(box[:width])}" height="#{format_num(box[:height])}" preserveAspectRatio="xMidYMid meet">)
+          lines << %(  <title>#{title_text}</title>) if title_text
+          lines << %(  <path d="#{path_data}" fill="currentColor" fill-rule="evenodd"/>)
+          lines << %(</svg>)
+          %(<?xml version="1.0" encoding="UTF-8"?>\n#{lines.join("\n")}\n)
+        end
+
+        # SVG path data with y already negated. Exposed for tests and
+        # for callers that want to embed the path in their own wrapper.
+        #
+        # @return [String]
+        def path_data
+          parts = []
+          @outline.to_commands.each do |cmd|
+            case cmd.first
+            when :move_to then parts << format_cmd("M", cmd[1], cmd[2])
+            when :line_to then parts << format_cmd("L", cmd[1], cmd[2])
+            when :curve_to
+              parts << format_cmd_q(cmd[1], cmd[2], cmd[3], cmd[4])
+            when :close_path then parts << "Z"
+            end
+          end
+          parts.join(" ")
+        end
+
+        private
+
+        def title_text
+          return nil unless @codepoint
+
+          label = "U+#{format("%04X", @codepoint)}"
+          label << " (Code Charts#{": #{@base_font}" if @base_font})"
+          label
+        end
+
+        def view_box
+          bb = @outline.bbox
+          if bb.nil? || empty_bbox?(bb)
+            return { min_x: 0, min_y: 0, width: 1, height: 1 }
+          end
+
+          min_x = bb[:x_min].to_f
+          max_x = bb[:x_max].to_f
+          min_y = bb[:y_min].to_f
+          max_y = bb[:y_max].to_f
+          width = (max_x - min_x).nonzero? || 1.0
+          height = (max_y - min_y).nonzero? || 1.0
+          pad_x = width * PaddingRatio
+          pad_y = height * PaddingRatio
+          {
+            min_x: min_x - pad_x,
+            min_y: -(max_y + pad_y),
+            width: width + (2 * pad_x),
+            height: height + (2 * pad_y),
+          }
+        end
+
+        def empty_bbox?(bb)
+          bb[:x_min] == 0 && bb[:y_min] == 0 && bb[:x_max] == 0 && bb[:y_max] == 0
+        end
+
+        def format_dims(box)
+          format("%<min_x>.2f %<min_y>.2f %<width>.2f %<height>.2f", box)
+        end
+
+        def format_cmd(letter, x, y)
+          "#{letter} #{format_num(x)} #{format_num(-y)}"
+        end
+
+        def format_cmd_q(cx, cy, ex, ey)
+          "Q #{format_num(cx)} #{format_num(-cy)} #{format_num(ex)} #{format_num(-ey)}"
+        end
+
+        def format_num(n)
+          if n.is_a?(Integer) || n.to_f == n.to_i
+            n.to_i.to_s
+          else
+            format("%.2f", n)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Parses a PDF ToUnicode CMap stream into a `{cid => codepoint}` Hash.
+      #
+      # PDF ToUnicode CMaps (Adobe Technical Note #5014) use a small
+      # PostScript-like syntax with three constructs that matter to us:
+      #
+      #   * `N begincodespacerange ... endcodespacerange` — declares the
+      #     valid code space. We ignore this; we just take whatever the
+      #     bfchar/bfrange entries hand us.
+      #   * `N beginbfchar ... endbfchar` — one-to-one cid → unicode
+      #     mappings, one pair per line: `<cid_hex> <uni_hex>`.
+      #   * `N beginbfrange ... endbfrange` — range mappings. Two forms:
+      #       * `<lo> <hi> <start>` — cids lo..hi map to consecutive
+      #         codepoints starting at `start`.
+      #       * `<lo> <hi> [<u1> <u2> ... <un>]` — explicit per-cid
+      #         mapping within the range.
+      #
+      # The unicode target string may encode one codepoint (4 hex digits
+      # for BMP, 8 for an astral codepoint via UTF-16 surrogate pair) or
+      # a sequence (multiple codepoints, used for ligatures). For our
+      # purposes — attributing one Code Charts glyph to one codepoint —
+      # we take the first codepoint of the target string and ignore the
+      # rest.
+      module ToUnicode
+        # @param cmap_text [String] raw decoded CMap stream text
+        # @return [Hash{Integer=>Integer}] frozen cid → codepoint map
+        def self.parse(cmap_text)
+          result = {}
+          scan_bfchar(cmap_text, result)
+          scan_bfrange(cmap_text, result)
+          result.freeze
+        end
+
+        class << self
+          private
+
+          def scan_bfchar(text, result)
+            text.scan(/beginbfchar\s*(.*?)\s*endbfchar/m) do
+              body = Regexp.last_match(1)
+              body.scan(/<([0-9A-Fa-f]+)>\s*<([0-9A-Fa-f]+)>/).each do |cid_h, uni_h|
+                cid = cid_h.to_i(16)
+                cp = decode_target(uni_h)
+                result[cid] = cp if cp
+              end
+            end
+          end
+
+          def scan_bfrange(text, result)
+            text.scan(/beginbfrange\s*(.*?)\s*endbfrange/m) do
+              body = Regexp.last_match(1)
+              # Match either `<lo> <hi> <start>` or `<lo> <hi> [<u1> ... <un>]`
+              body.scan(/<([0-9A-Fa-f]+)>\s*<([0-9A-Fa-f]+)>\s*(?:<([0-9A-Fa-f]+)>|\[([^\]]*)\])/).each do |lo_h, hi_h, start_h, arr|
+                lo = lo_h.to_i(16)
+                hi = hi_h.to_i(16)
+                if start_h
+                  start = decode_target(start_h)
+                  next unless start
+                  (lo..hi).each_with_index do |cid, i|
+                    result[cid] = start + i
+                  end
+                elsif arr
+                  entries = arr.scan(/<([0-9A-Fa-f]+)>/).flatten
+                  entries.each_with_index do |uni_h, i|
+                    cid = lo + i
+                    break if cid > hi
+                    cp = decode_target(uni_h)
+                    result[cid] = cp if cp
+                  end
+                end
+              end
+            end
+          end
+
+          # Decode a CMap target hex string into a single codepoint.
+          # The target may be 4 hex digits (BMP), 8 (UTF-16 surrogate pair
+          # for astral), or longer (a sequence — we take the first cp).
+          #
+          # @param hex [String] hexadecimal digits
+          # @return [Integer, nil] the first codepoint, or nil if hex is empty
+          def decode_target(hex)
+            return nil if hex.nil? || hex.empty?
+            return hex.to_i(16) if hex.length == 4
+
+            if hex.length >= 8 && hex.length % 4 == 0
+              first = hex[0, 4].to_i(16)
+              if first >= 0xD800 && first <= 0xDBFF
+                second = hex[4, 4].to_i(16)
+                return 0x10000 + ((first - 0xD800) << 10) + (second - 0xDC00)
+              end
+              return first
+            end
+
+            hex[0, 4].to_i(16)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "renderer"
+require_relative "../../repo/atomic_writes"
+require_relative "../../repo/paths"
+
+module Ucode
+  module Glyphs
+    module EmbeddedFonts
+      # Writes one `glyph.svg` per codepoint in `codepoints`, sourcing
+      # the outline from the Code Charts PDF's embedded font program.
+      #
+      # The Catalog and Renderer are shared across the loop so the
+      # expensive PDF walk + ToUnicode parse + fontisan load happen
+      # once per process. Each FontEntry memoizes its own fontisan
+      # accessor; in long CJK runs you may want to call
+      # `entry.reset_accessor!` periodically (the Writer doesn't).
+      #
+      # Idempotent and atomic via `Repo::AtomicWrites` — same protocol
+      # as the LastResort and v0.1 cell-extractor writers.
+      class Writer
+        include Repo::AtomicWrites
+
+        # @param output_root [String, Pathname]
+        # @param catalog [Catalog]
+        def initialize(output_root:, catalog:)
+          @output_root = Pathname.new(output_root)
+          @catalog = catalog
+          @renderer = Renderer.new(catalog)
+        end
+
+        # Write `glyph.svg` for every codepoint covered by the PDF.
+        #
+        # @param codepoints [Array<Integer>, Enumerable<Integer>] which
+        #   codepoints to render. Defaults to all codepoints the Catalog
+        #   has fonts for.
+        # @param block_lookup [Proc, #call] codepoint → block id string
+        #   (e.g. `"Basic_Latin"`). Returns nil for codepoints without
+        #   a block; those are skipped.
+        # @return [Hash] tally `{ written:, skipped:, missing:, total: }`
+        def write_many(codepoints = nil, block_lookup:)
+          cps = codepoints || @catalog.codepoints
+          tally = { written: 0, skipped: 0, missing: 0, total: 0 }
+          cps.each do |cp|
+            tally[:total] += 1
+            block_id = block_lookup.call(cp)
+            if block_id.nil?
+              tally[:missing] += 1
+              next
+            end
+
+            result = @renderer.render(cp)
+            if result.nil? || !result.ok?
+              tally[:missing] += 1
+              next
+            end
+
+            written = write_glyph(block_id, cp, result.svg)
+            tally[written ? :written : :skipped] += 1
+          end
+          tally
+        end
+
+        private
+
+        def write_glyph(block_id, codepoint, svg)
+          cp_id = Repo::Paths.cp_id(codepoint)
+          path = Repo::Paths.codepoint_glyph_path(@output_root, block_id, cp_id)
+          write_atomic(path, svg)
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/embedded_fonts.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Glyphs
+    # Code Charts PDF font-stream extraction — pillar 1 of the v0.2 glyph
+    # strategy.
+    #
+    # The Unicode Code Charts PDFs (per-block or the `CodeCharts.pdf`
+    # monolith) embed one subsetted CID-keyed font per "script group"
+    # shown in the charts. Each font is a Type0 font whose descendant
+    # CIDFont uses `/CIDToGIDMap /Identity` — so the 2-byte character
+    # code used in the page's text-show operators IS the GID into the
+    # embedded font program. The codepoint mapping lives in the Type0
+    # font's `/ToUnicode` CMap stream.
+    #
+    # The pipeline is therefore:
+    #
+    #   1. {Catalog} walks the PDF's fonts (via `mutool info`) and builds
+    #      a global `{codepoint => [font_entry, gid]}` index by parsing
+    #      every Type0 font's ToUnicode CMap.
+    #   2. {Renderer} looks up a codepoint, lazily extracts the font's
+    #      stream to a cache file, loads it via `fontisan`, and asks for
+    #      the outline at the resolved GID.
+    #   3. {Svg} wraps the fontisan outline as a standalone SVG document
+    #      (y-flipped, viewBox-padded) — same shape as the LastResort
+    #      SVGs so downstream consumers don't care which pillar produced
+    #      the glyph.
+    #
+    # The v0.1 cell extractor operated on rendered PDF pages and was
+    # defeated by the chart cell border being composited into the same
+    # glyph as the outline. Going straight to the embedded font program
+    # sidesteps that bug entirely: the font's outlines are clean
+    # vector geometry with no page chrome.
+    #
+    # System dependency: `mutool` (mupdf-tools) is on the PATH. Used for
+    # `mutool info` (font enumeration) and `mutool show -b -o` (raw
+    # stream extraction).
+    module EmbeddedFonts
+      autoload :Source, "ucode/glyphs/embedded_fonts/source"
+      autoload :ToUnicode, "ucode/glyphs/embedded_fonts/tounicode"
+      autoload :FontEntry, "ucode/glyphs/embedded_fonts/font_entry"
+      autoload :Catalog, "ucode/glyphs/embedded_fonts/catalog"
+      autoload :ContentStreamCorrelator,
+               "ucode/glyphs/embedded_fonts/content_stream_correlator"
+      autoload :Svg, "ucode/glyphs/embedded_fonts/svg"
+      autoload :Renderer, "ucode/glyphs/embedded_fonts/renderer"
+      autoload :Writer, "ucode/glyphs/embedded_fonts/writer"
+    end
+  end
+end

data/lib/ucode/glyphs/grid.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Glyphs
+    Grid = Struct.new(
+      :origin_x, :origin_y,
+      :column_pitch, :row_pitch,
+      :columns, :rows,
+      :block_first_cp,
+      keyword_init: true,
+    ) do
+      def cell_position(codepoint)
+        offset = codepoint - block_first_cp
+        return nil if offset.negative?
+
+        row, col = offset.divmod(columns)
+        return nil if row >= rows
+
+        [origin_x + (col * column_pitch), origin_y + (row * row_pitch)]
+      end
+
+      def codepoint_at(row, col)
+        return nil if row.negative? || row >= rows
+        return nil if col.negative? || col >= columns
+
+        block_first_cp + (row * columns) + col
+      end
+    end
+  end
+end