ucode 0.1.0

data/lib/ucode/glyphs/grid_detector.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+require "ucode/glyphs/grid"
+require "ucode/glyphs/path_bbox"
+
+module Ucode
+  module Glyphs
+    # Detects the chart grid in a Code Charts PDF page rendered to SVG.
+    #
+    # The PDF page produced by pdftocairo / pdf2svg / dvisvgm contains
+    # every visible element (title, block name, row labels, codepoint
+    # digits, and the actual character glyphs) as positioned `<use>`
+    # references into a `<defs>` block of named glyph outlines. The
+    # character cells we want to extract correspond to glyphs whose
+    # bounding box is larger than every label or digit font on the
+    # page — the chart's character samples are drawn at a larger size
+    # than any of the surrounding text.
+    #
+    # Algorithm:
+    #   1. Walk `<defs>`, estimate each glyph's bbox via `PathBbox`.
+    #   2. Classify a glyph as "character-sized" when its width and
+    #      height both exceed `CharSizeThreshold` (default 8 pt).
+    #      This excludes title, row-label, and digit glyphs while
+    #      keeping every actual character sample — including pages
+    #      where the chart mixes multiple character fonts (e.g. the
+    #      Basic Latin page uses one font for punctuation/digits and
+    #      another for letters).
+    #   3. Collect every `<use>` that references a character-sized
+    #      glyph; these are the cell origins.
+    #   4. Cluster the Y values of those uses into rows, and within
+    #      each row cluster the X values into columns.
+    #   5. Drop rows whose column count diverges from the modal value
+    #      (these are footer/header artifacts, not chart rows).
+    #   6. Return a `Grid` value object anchored at the top-left cell
+    #      with uniform column/row pitches derived from the median
+    #      spacing between adjacent clusters.
+    #
+    # This is pure (no I/O). The detector takes a parsed Nokogiri
+    # document and returns a `Grid`.
+    class GridDetector
+      CharSizeThreshold = 8.0
+      ClusterEpsilon = 15.0
+      private_constant :CharSizeThreshold, :ClusterEpsilon
+
+      class << self
+        # @param doc [Nokogiri::XML::Document]
+        # @param block_first_cp [Integer] first codepoint of the block;
+        #   stored on the Grid so callers can map codepoint ↔ cell.
+        # @return [Ucode::Glyphs::Grid, nil] nil if no character grid
+        #   could be detected.
+        def detect(doc, block_first_cp:)
+          uses = collect_uses(doc)
+          return nil if uses.empty?
+
+          char_glyph_ids = char_sized_glyph_ids(doc)
+          return nil if char_glyph_ids.empty?
+
+          cell_uses = uses.select { |u| char_glyph_ids.include?(u.glyph_id) }
+          return nil if cell_uses.empty?
+
+          build_grid(cell_uses, block_first_cp)
+        end
+
+        private
+
+        UsePosition = Struct.new(:x, :y, :glyph_id, :set_id, keyword_init: true)
+
+        def collect_uses(doc)
+          doc.css("use").map do |node|
+            href = node["xlink:href"] || node["href"] || ""
+            glyph_id = href.sub(/\A#/, "")
+            match = glyph_id.match(/\Aglyph-(\d+)-(\d+)\z/)
+            next nil unless match
+
+            UsePosition.new(
+              x: node["x"].to_f,
+              y: node["y"].to_f,
+              glyph_id: glyph_id,
+              set_id: match[1].to_i,
+            )
+          end.compact
+        end
+
+        def char_sized_glyph_ids(doc)
+          doc.css("defs g[id^='glyph-']").each_with_object({}) do |g, acc|
+            id = g["id"]
+            next unless id =~ /\Aglyph-\d+-\d+\z/
+
+            paths = g.css("path")
+            next if paths.empty?
+
+            bbox = paths.map { |p| PathBbox.estimate(p["d"]) }.reject(&:empty?).reduce do |a, b|
+              PathBbox::Result.new(
+                min_x: [a.min_x, b.min_x].min,
+                min_y: [a.min_y, b.min_y].min,
+                max_x: [a.max_x, b.max_x].max,
+                max_y: [a.max_y, b.max_y].max,
+              )
+            end
+            next unless bbox
+
+            acc[id] = true if char_sized?(bbox)
+          end
+        end
+
+        def char_sized?(bbox)
+          bbox.width >= CharSizeThreshold && bbox.height >= CharSizeThreshold
+        end
+
+        def median(values)
+          return 0.0 if values.empty?
+
+          sorted = values.sort
+          mid = sorted.size / 2
+          sorted.size.even? ? (sorted[mid - 1] + sorted[mid]) / 2.0 : sorted[mid]
+        end
+
+        def build_grid(cell_uses, block_first_cp)
+          row_clusters = cluster_by_value(cell_uses, :y)
+          return nil if row_clusters.empty?
+
+          column_clusters = cluster_by_value(cell_uses, :x)
+          return nil if column_clusters.empty?
+
+          column_starts = column_clusters.map { |c| c.map(&:x).min }.sort
+          row_starts = row_clusters.map { |c| c.map(&:y).min }.sort
+
+          Grid.new(
+            origin_x: column_starts.first,
+            origin_y: row_starts.first,
+            column_pitch: median_pitch(column_starts),
+            row_pitch: median_pitch(row_starts),
+            columns: column_starts.size,
+            rows: row_starts.size,
+            block_first_cp: block_first_cp,
+          )
+        end
+
+        def cluster_by_value(items, attr)
+          sorted = items.sort_by { |i| i.public_send(attr) }
+          clusters = []
+          sorted.each do |item|
+            value = item.public_send(attr)
+            if clusters.empty? || (value - clusters.last[:max]).abs > ClusterEpsilon
+              clusters << { max: value, items: [item] }
+            else
+              clusters.last[:max] = value
+              clusters.last[:items] << item
+            end
+          end
+          clusters.map { |c| c[:items] }
+        end
+
+        def median_pitch(sorted_values)
+          return 0.0 if sorted_values.size < 2
+
+          pitches = sorted_values.each_cons(2).map { |a, b| b - a }
+          median(pitches)
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/last_resort/cmap_index.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+require "ucode/error"
+
+module Ucode
+  module Glyphs
+    module LastResort
+      # Parses the Last Resort Font `cmap-f13.ttx` once into a flat
+      # `{codepoint_int => glyph_name}` lookup.
+      #
+      # The Format 13 cmap has 1,114,112 entries (every codepoint from
+      # U+0000 to U+10FFFF). Each entry looks like:
+      #
+      #   <map code="0x0" name="lastresortlatin"/>
+      #
+      # We parse every `<map>` child of every `<cmap_format_*>` element,
+      # ignore the platform/encoding attributes (Format 13 only here),
+      # and build a single Hash. Memory cost is ~80 MB for the parsed
+      # Hash on Ruby 3.x — acceptable for the CLI, paid once per run.
+      #
+      # For long-running processes (e.g. the site dev server), the
+      # parsed index can be cached via the optional `cache:` constructor
+      # argument. The cache contract is `cache.read(key) -> Hash | nil`
+      # and `cache.write(key, hash) -> void`; pass an object with both
+      # methods (e.g. `Ucode::Cache`).
+      class CmapIndex
+        CodeAttr = "code"
+        private_constant :CodeAttr
+
+        NameAttr = "name"
+        private_constant :NameAttr
+
+        # Parse the cmap file at `path` and return a frozen Hash.
+        #
+        # @param path [String, Pathname, #to_path] cmap-f13.ttx path
+        # @return [Hash{Integer=>String}] codepoint → glyph name
+        def self.parse(path)
+          new(path).to_h
+        end
+
+        # @param path [String, Pathname, #to_path] cmap-f13.ttx path
+        def initialize(path)
+          @path = Pathname.new(path)
+        end
+
+        # @return [Hash{Integer=>String}] frozen codepoint → glyph name
+        def to_h
+          @to_h ||= build_index.freeze
+        end
+
+        # @param codepoint [Integer]
+        # @return [String, nil] glyph name or nil if no entry
+        def [](codepoint)
+          to_h[codepoint]
+        end
+
+        # @return [Boolean]
+        def key?(codepoint)
+          to_h.key?(codepoint)
+        end
+
+        # @return [Integer] number of entries
+        def size
+          to_h.size
+        end
+
+        private
+
+        def build_index
+          doc = Nokogiri::XML(@path.read) do |config|
+            config.noblanks.strict
+          end
+          index = {}
+          doc.xpath("/ttFont/cmap/cmap_format_13/map").each do |node|
+            code = parse_code(node[CodeAttr])
+            name = node[NameAttr]
+            next if code.nil? || name.nil? || name.empty?
+
+            index[code] = name
+          end
+          index
+        end
+
+        def parse_code(raw)
+          return nil if raw.nil? || raw.empty?
+
+          raw.start_with?("0x", "0X") ? raw[2..].to_i(16) : raw.to_i(16)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/last_resort/contents.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ucode
+  module Glyphs
+    module LastResort
+      # Parses the UFO `contents.plist` once into a
+      # `{glyph_name => glif_basename}` lookup.
+      #
+      # The plist is the standard UFO v3 format:
+      #
+      #   <dict>
+      #     <key>lastresortlatin</key>
+      #     <string>lastresortlatin.glif</string>
+      #     ...
+      #   </dict>
+      #
+      # 380 entries (one per placeholder glyph). Tiny file, but parsing
+      # it once per Writer avoids 380 redundant Nokogiri passes across
+      # the per-codepoint loop.
+      class Contents
+        KeyEl = "key"
+        private_constant :KeyEl
+
+        StringEl = "string"
+        private_constant :StringEl
+
+        # Parse the plist file at `path` and return a frozen Hash.
+        #
+        # @param path [String, Pathname, #to_path] contents.plist path
+        # @return [Hash{String=>String}] glyph name → glif basename
+        def self.parse(path)
+          new(path).to_h
+        end
+
+        # @param path [String, Pathname, #to_path] contents.plist path
+        def initialize(path)
+          @path = Pathname.new(path)
+        end
+
+        # @return [Hash{String=>String}] frozen glyph name → glif basename
+        def to_h
+          @to_h ||= build_index.freeze
+        end
+
+        # @param glyph_name [String]
+        # @return [String, nil] glif basename (e.g. "lastresortlatin.glif")
+        def [](glyph_name)
+          to_h[glyph_name]
+        end
+
+        # @return [Boolean]
+        def key?(glyph_name)
+          to_h.key?(glyph_name)
+        end
+
+        private
+
+        def build_index
+          doc = Nokogiri::XML(@path.read) do |config|
+            config.noblanks.strict
+          end
+          pairs = doc.xpath("/plist/dict/*").each_slice(2)
+          pairs.each_with_object({}) do |(key_node, val_node), hash|
+            next unless key_node.name == KeyEl && val_node&.name == StringEl
+
+            hash[key_node.text] = val_node.text
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/last_resort/glif.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+require "ucode/error"
+
+module Ucode
+  module Glyphs
+    module LastResort
+      # Parses one UFO `.glif` outline file into a {Glif::Outline} value
+      # object: advance width + list of contours, each contour being a
+      # list of {Glif::Point}s.
+      #
+      # UFO point semantics:
+      #
+      #   * `type="move"`    — on-curve; starts a new contour.
+      #   * `type="line"`    — on-curve; straight line from previous.
+      #   * `type="curve"`   — on-curve; cubic Bezier. The preceding 1–2
+      #                        points with no `type` are off-curve control
+      #                        points.
+      #   * `type="qcurve"`  — on-curve; quadratic Bezier. Preceding N
+      #                        points with no `type` are off-curve controls.
+      #   * no `type`        — off-curve control point.
+      #
+      # Contours are implicitly closed (UFO follows PostScript
+      # convention). {Svg} adds the closing `Z` when emitting SVG path
+      # data, so the outline representation here is open.
+      #
+      # All coordinates are in font units (integers in the Last Resort
+      # UFO; the parser accepts floats too for forward compatibility).
+      module Glif
+        # Single outline point. `kind` is one of `:offcurve`, `:move`,
+        # `:line`, `:curve`, `:qcurve`.
+        Point = Struct.new(:x, :y, :kind, keyword_init: true) do
+          def on_curve?
+            kind != :offcurve
+          end
+        end
+
+        # One contour — an ordered list of {Point}s.
+        Contour = Struct.new(:points, keyword_init: true)
+
+        # Parsed outline value object.
+        Outline = Struct.new(:advance, :contours, keyword_init: true) do
+          def bbox
+            return nil if contours.empty?
+
+            xs = []
+            ys = []
+            contours.each do |contour|
+              contour.points.each do |point|
+                xs << point.x
+                ys << point.y
+              end
+            end
+            return nil if xs.empty?
+
+            { min_x: xs.min, min_y: ys.min, max_x: xs.max, max_y: ys.max }
+          end
+        end
+
+        # @param path [String, Pathname, #to_path] `.glif` file path
+        # @return [Outline]
+        def self.read(path)
+          parse(Pathname.new(path))
+        end
+
+        # @param path [String, Pathname, #to_path] `.glif` file path
+        # @return [Outline]
+        def self.parse(path)
+          doc = Nokogiri::XML(path.read) do |config|
+            config.noblanks.strict
+          end
+          glyph = doc.at_xpath("/glyph") || doc.at_xpath("//glyph")
+          raise Ucode::GlyphError, "not a UFO .glif file: #{path}" unless glyph
+
+          advance = parse_advance(glyph)
+          contours = parse_contours(glyph)
+          Outline.new(advance: advance, contours: contours)
+        end
+
+        class << self
+          private
+
+          def parse_advance(glyph)
+            node = glyph.at_xpath("advance")
+            return 0 unless node
+
+            width = node["width"]
+            width ? width.to_i : 0
+          end
+
+          def parse_contours(glyph)
+            outline_node = glyph.at_xpath("outline")
+            return [] unless outline_node
+
+            outline_node.xpath("contour").map do |contour_node|
+              points = contour_node.xpath("point").map do |point_node|
+                Point.new(
+                  x: point_node["x"].to_i,
+                  y: point_node["y"].to_i,
+                  kind: parse_kind(point_node["type"]),
+                )
+              end
+              Contour.new(points: points)
+            end
+          end
+
+          def parse_kind(type)
+            case type
+            when nil      then :offcurve
+            when "move"   then :move
+            when "line"   then :line
+            when "curve"  then :curve
+            when "qcurve" then :qcurve
+            else
+              raise Ucode::GlyphError, "unknown glif point type: #{type.inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "ucode/error"
+require "ucode/glyphs/last_resort/cmap_index"
+require "ucode/glyphs/last_resort/contents"
+require "ucode/glyphs/last_resort/glif"
+require "ucode/glyphs/last_resort/svg"
+
+module Ucode
+  module Glyphs
+    module LastResort
+      # Chains the four lookup stages needed to render one codepoint's
+      # Last Resort glyph: cmap (cp → name) → contents (name → file)
+      # → glif (file → outline) → svg (outline → SVG document).
+      #
+      # The CmapIndex and Contents are lazily built and memoized per
+      # Renderer instance, so rendering many codepoints shares the
+      # parsed cmap (1,114,112 entries) and plist (380 entries).
+      #
+      # Pure-ish: reads from disk via the Source paths; produces a
+      # {Result} struct. Never raises on missing codepoints — returns
+      # `nil` so callers can decide whether to log or fall back to a
+      # generic placeholder.
+      class Renderer
+        # Result of rendering one codepoint.
+        Result = Struct.new(:codepoint, :glyph_name, :svg, keyword_init: true) do
+          def ok?
+            !svg.nil?
+          end
+        end
+
+        # @param source [Source]
+        def initialize(source)
+          @source = source
+        end
+
+        # @param codepoint [Integer]
+        # @return [Result, nil] nil when the codepoint isn't in the cmap
+        #   or the named glyph is missing from disk
+        def render(codepoint)
+          glyph_name = cmap[codepoint]
+          return nil unless glyph_name
+
+          basename = contents[glyph_name]
+          return nil unless basename
+
+          path = @source.glif_path(basename)
+          return nil unless path.exist?
+
+          outline = Glif.read(path)
+          svg = Svg.new(outline, codepoint: codepoint).to_s
+          Result.new(codepoint: codepoint, glyph_name: glyph_name, svg: svg)
+        end
+
+        # @return [CmapIndex]
+        def cmap
+          @cmap ||= CmapIndex.new(@source.cmap_path)
+        end
+
+        # @return [Contents]
+        def contents
+          @contents ||= Contents.new(@source.contents_path)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/error"
+
+module Ucode
+  module Glyphs
+    module LastResort
+      # Locates the Last Resort Font UFO source on disk.
+      #
+      # Resolution order (first match wins):
+      #
+      #   1. Explicit `root:` argument.
+      #   2. `UCODE_LAST_RESORT_FONT_ROOT` environment variable.
+      #   3. `Ucode::Config#last_resort_font_root` (if configured).
+      #   4. Conventional sibling-of-repo path `../../external/unicode/
+      #      last-resort-font` relative to the gem root.
+      #
+      # The UFO must contain:
+      #
+      #   * `cmap-f13.ttx` — Format 13 cmap (cp → glyph name).
+      #   * `font.ufo/glyphs/contents.plist` — glyph name → .glif file.
+      #   * `font.ufo/glyphs/*.glif` — outline files.
+      #
+      # If any required artifact is missing, the constructor raises
+      # {Ucode::LastResortMissingError} with a `context:` payload listing
+      # the resolved root and which artifact is absent. The CLI catches
+      # this to print a friendly "see README for setup" message.
+      class Source
+        attr_reader :root, :cmap_path, :glyphs_dir, :contents_path
+
+        # Expected layout inside the UFO root.
+        CMAP_REL = "cmap-f13.ttx"
+        private_constant :CMAP_REL
+
+        GLYPHS_REL = "font.ufo/glyphs"
+        private_constant :GLYPHS_REL
+
+        CONTENTS_REL = "font.ufo/glyphs/contents.plist"
+        private_constant :CONTENTS_REL
+
+        # @param root [String, Pathname, nil] explicit UFO root
+        # @param env [Hash{String=>String}] env var source (defaults to ENV)
+        # @param gem_root [String, Pathname, nil] gem root for the
+        #   conventional fallback (defaults to the directory holding
+        #   `lib/ucode`); injectable for tests
+        # @raise [Ucode::LastResortMissingError] if a required artifact
+        #   is missing at the resolved root
+        def initialize(root: nil, env: ENV, gem_root: nil)
+          @root = resolve_root(root, env, gem_root)
+          validate!
+        end
+
+        # @return [Boolean] true if all required artifacts are present
+        def available?
+          [
+            @cmap_path,
+            @glyphs_dir,
+            @contents_path,
+          ].all?(&:exist?)
+        end
+
+        # Path to a specific `.glif` file by basename. Does NOT verify
+        # the file exists; callers resolve via {Contents} first.
+        #
+        # @param basename [String] e.g. "lastresortlatin.glif"
+        # @return [Pathname]
+        def glif_path(basename)
+          @glyphs_dir.join(basename)
+        end
+
+        private
+
+        def resolve_root(explicit, env, gem_root)
+          return Pathname.new(explicit).expand_path if explicit
+
+          candidates = []
+          env_val = env["UCODE_LAST_RESORT_FONT_ROOT"]
+          candidates << Pathname.new(env_val) if env_val && !env_val.empty?
+          candidates << conventional_path(gem_root)
+          candidates.find { |c| c.exist? && looks_like_ufo_root?(c) }
+        end
+
+        def conventional_path(gem_root)
+          base = gem_root ? Pathname.new(gem_root) : default_gem_root
+          # gem_root is the project root (e.g. /.../fontist/ucode).
+          # The Last Resort Font is conventionally checked out as a
+          # sibling-of-the-workspace at <workspace>/external/unicode/
+          # last-resort-font — that's two levels up from the gem root.
+          base.expand_path.parent.parent.join("external", "unicode", "last-resort-font")
+        end
+
+        def default_gem_root
+          # __dir__ = lib/ucode/glyphs/last_resort. Four `..` get us back
+          # to the project root (the directory containing `lib/`).
+          Pathname.new(__dir__).join("..", "..", "..", "..")
+        end
+
+        def looks_like_ufo_root?(path)
+          path.join("font.ufo", "glyphs").directory?
+        end
+
+        def validate!
+          raise_missing if @root.nil?
+
+          @cmap_path = @root.join(CMAP_REL)
+          @glyphs_dir = @root.join(GLYPHS_REL)
+          @contents_path = @root.join(CONTENTS_REL)
+          raise_missing unless available?
+        end
+
+        def raise_missing
+          raise Ucode::LastResortMissingError.new(
+            "Last Resort Font UFO source not found",
+            context: {
+              resolved_root: @root&.to_s,
+              env_var: "UCODE_LAST_RESORT_FONT_ROOT",
+            },
+          )
+        end
+      end
+    end
+  end
+end