ucode 0.1.0

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

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "ucode/glyphs/last_resort/glif"
+
+module Ucode
+  module Glyphs
+    module LastResort
+      # Converts a {Glif::Outline} into a standalone SVG document.
+      #
+      # Two transforms are applied:
+      #
+      #   1. **Y-axis flip.** UFO point y grows upward (PostScript
+      #      convention); SVG y grows downward. We reflect y about the
+      #      glyph's vertical midpoint so the rendered glyph appears
+      #      upright.
+      #
+      #   2. **ViewBox normalization.** The viewBox is set to the
+      #      outline's bounding box, with a small padding so strokes
+      #      are not clipped at the edges. The `width`/`height`
+      #      attributes match the viewBox aspect ratio so consumers
+      #      can scale via CSS.
+      #
+      # Path data semantics:
+      #
+      #   * `move`   → `M x y`
+      #   * `line`   → `L x y`
+      #   * `curve`  → `C cx1 cy1 cx2 cy2 x y` (cubic; preceding 1–2
+      #               off-curve points are control points)
+      #   * `qcurve` → `Q cx cy x y` (quadratic; ≥1 preceding off-curve
+      #               points; multiple off-curves are emitted as chained
+      #               quadratic segments with implicit on-curve midpoints
+      #               per the UFO spec)
+      #
+      # Contours are closed with `Z` per UFO convention.
+      class Svg
+        # Padding ratio applied around the glyph bbox for the viewBox.
+        PaddingRatio = 0.08
+        private_constant :PaddingRatio
+
+        # @param outline [Glif::Outline]
+        # @param codepoint [Integer, nil] optional codepoint for the
+        #   `<title>` element (accessibility + debugging)
+        def initialize(outline, codepoint: nil)
+          @outline = outline
+          @codepoint = codepoint
+        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>U+#{format("%04X", @codepoint)} (Last Resort)</title>) if @codepoint
+          lines << %(  <path d="#{path_data.strip}" fill="currentColor" fill-rule="evenodd"/>)
+          lines << %(</svg>)
+          %(<?xml version="1.0" encoding="UTF-8"?>\n#{lines.join("\n")}\n)
+        end
+
+        # Just the path `d` attribute — exposed for tests and for callers
+        # that want to embed the path inside their own SVG wrapper.
+        #
+        # @return [String]
+        def path_data
+          @outline.contours.map { |contour| PathBuilder.new(contour.points).to_path }.join(" ")
+        end
+
+        private
+
+        def format_dims(box)
+          format("%<min_x>.2f %<min_y>.2f %<width>.2f %<height>.2f", box)
+        end
+
+        # Build the SVG viewBox with padding around the glyph bbox.
+        # Returns min_x, min_y, width, height — already y-flipped so
+        # min_y is the top edge in SVG space.
+        def view_box
+          bbox = @outline.bbox
+          if bbox.nil?
+            return { min_x: 0, min_y: 0, width: 1, height: 1 }
+          end
+
+          min_x = bbox[:min_x].to_f
+          max_x = bbox[:max_x].to_f
+          min_y = bbox[:min_y].to_f
+          max_y = bbox[:max_y].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 format_num(n)
+          if n.to_f == n.to_i
+            n.to_i.to_s
+          else
+            format("%.2f", n)
+          end
+        end
+      end
+
+      # Internal helper: walks a contour's points and emits SVG path
+      # commands per the UFO point-type rules.
+      #
+      # Contour-start handling: the first on-curve point we encounter
+      # becomes the implicit `M` target. We do NOT also emit `L`/`C`/
+      # `Q` for it — that would draw a degenerate zero-length segment.
+      # Subsequent on-curve points emit their proper command.
+      class PathBuilder
+        def initialize(points)
+          @points = points
+          @out = +""
+          @i = 0
+          @pending_offcurve = []
+          @last_oncurve = nil
+          @started = false
+        end
+
+        def to_path
+          until @i >= @points.length
+            point = @points[@i]
+            case point.kind
+            when :offcurve then consume_offcurve(point)
+            when :move     then emit_move(point)
+            when :line     then emit_line(point)
+            when :curve    then emit_curve(point)
+            when :qcurve   then emit_qcurve(point)
+            end
+            @i += 1
+          end
+          flush_trailing_offcurve
+          append_close
+          @out.strip
+        end
+
+        private
+
+        def consume_offcurve(point)
+          @pending_offcurve << point
+        end
+
+        def emit_move(point)
+          @out << "M #{flip_xy(point)} "
+          @last_oncurve = point
+          @started = true
+        end
+
+        def emit_line(point)
+          return start_contour(point) unless @started
+
+          @out << "L #{flip_xy(point)} "
+          @last_oncurve = point
+        end
+
+        def emit_curve(point)
+          return start_contour(point) unless @started
+
+          c1 = @pending_offcurve[0] || point
+          c2 = @pending_offcurve[1] || point
+          @out << "C #{flip_xy(c1)} #{flip_xy(c2)} #{flip_xy(point)} "
+          @pending_offcurve.clear
+          @last_oncurve = point
+        end
+
+        def emit_qcurve(point)
+          return start_contour(point) unless @started
+
+          if @pending_offcurve.length == 1
+            ctrl = @pending_offcurve[0]
+            @out << "Q #{flip_xy(ctrl)} #{flip_xy(point)} "
+          else
+            emit_qcurve_chain(@pending_offcurve, point)
+          end
+          @pending_offcurve.clear
+          @last_oncurve = point
+        end
+
+        # When a contour's first point is not an explicit `move`, the
+        # first on-curve point we hit (curve/line/qcurve) is the
+        # implicit start. Emit just `M` for it; any pending off-curves
+        # are wrap-around controls that flush via {flush_trailing_offcurve}.
+        def start_contour(point)
+          @out << "M #{flip_xy(point)} "
+          @last_oncurve = point
+          @started = true
+        end
+
+        def emit_qcurve_chain(controls, terminal)
+          controls.each_with_index do |ctrl, idx|
+            next_ctrl = controls[idx + 1]
+            if next_ctrl.nil?
+              @out << "Q #{flip_xy(ctrl)} #{flip_xy(terminal)} "
+            else
+              mid_x = (ctrl.x + next_ctrl.x) / 2.0
+              mid_y = (ctrl.y + next_ctrl.y) / 2.0
+              @out << "Q #{flip_xy(ctrl)} #{flip_xy_struct(mid_x, mid_y)} "
+            end
+          end
+        end
+
+        def append_close
+          @out << "Z"
+        end
+
+        # UFO contours are implicitly closed. If off-curve points
+        # remain unflushed at the end of the contour, they are the
+        # wrap-around control points leading back to the contour's
+        # first on-curve point. Emit them as a final curve to that
+        # start point; the closing `Z` then completes the geometry.
+        def flush_trailing_offcurve
+          return if @pending_offcurve.empty? || @last_oncurve.nil?
+
+          endpoint = @last_oncurve
+          if @pending_offcurve.length == 1
+            @out << "Q #{flip_xy(@pending_offcurve[0])} #{flip_xy(endpoint)} "
+          else
+            emit_qcurve_chain(@pending_offcurve, endpoint)
+          end
+        end
+
+        def flip_xy(point)
+          flip_xy_struct(point.x, point.y)
+        end
+
+        # UFO y grows up; SVG y grows down. We negate y — the viewBox
+        # translation handles the vertical offset so the glyph appears
+        # upright in user space.
+        def flip_xy_struct(x, y)
+          "#{format_num(x)} #{format_num(-y)}"
+        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/last_resort/writer.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/glyphs/last_resort/renderer"
+require "ucode/glyphs/last_resort/source"
+require "ucode/repo/atomic_writes"
+require "ucode/repo/paths"
+
+module Ucode
+  module Glyphs
+    module LastResort
+      # Writes one `glyph.svg` per codepoint in `codepoints`, sourcing
+      # the outline from the Last Resort UFO.
+      #
+      # Single Renderer instance shared across the loop, so the parsed
+      # cmap and contents.plist are paid for once.
+      #
+      # **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.
+      #
+      # Block membership is the caller's responsibility — the Writer
+      # doesn't gate codepoints by assigned/unassigned. Last Resort
+      # placeholders exist for every codepoint in the cmap, including
+      # assigned ones, but the v0.2 pipeline only writes Last Resort
+      # SVGs for codepoints whose chart cell shows a placeholder box
+      # (see README "two pillars").
+      class Writer
+        include Repo::AtomicWrites
+
+        # @param output_root [String, Pathname]
+        # @param source [Source]
+        def initialize(output_root:, source:)
+          @output_root = Pathname.new(output_root)
+          @source = source
+          @renderer = Renderer.new(source)
+        end
+
+        # Write `glyph.svg` for every codepoint in `codepoints` whose
+        # block is known, using the Last Resort outline.
+        #
+        # @param codepoints [Array<Integer>, Enumerable<Integer>]
+        # @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, block_lookup:)
+          tally = { written: 0, skipped: 0, missing: 0, total: 0 }
+          codepoints.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/last_resort.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ucode
+  module Glyphs
+    # Last Resort Font integration — pillar 2 of the v0.2 glyph strategy.
+    #
+    # For codepoints whose Code Charts cell shows a placeholder box
+    # (unassigned, noncharacter, PUA), the chart glyph is drawn from
+    # Unicode's Last Resort Font. The Last Resort Font ships as a UFO
+    # source with two parts that matter to us:
+    #
+    #   * `cmap-f13.ttx` — a Format 13 `cmap` that maps every codepoint
+    #     (0x0..0x10FFFF) to a placeholder glyph name. 1,114,112 entries.
+    #   * `font.ufo/glyphs/*.glif` — 380 outline files, one per Unicode
+    #     block + a handful of special types (`notdef`,
+    #     `notdefplanezero`, the noncharacter / unassigned planes, …).
+    #   * `font.ufo/glyphs/contents.plist` — glyph name → `.glif` file.
+    #
+    # The pipeline is read-only and stateless: cmap (cp → name) →
+    # contents (name → file) → glif (file → outline) → svg (outline →
+    # SVG document). No PDF parsing, no cell extraction, no border
+    # compositing — the placeholder outline is exactly what the Code
+    # Charts display.
+    #
+    # See {Source} for how to locate the UFO on disk.
+    module LastResort
+      autoload :Source, "ucode/glyphs/last_resort/source"
+      autoload :CmapIndex, "ucode/glyphs/last_resort/cmap_index"
+      autoload :Contents, "ucode/glyphs/last_resort/contents"
+      autoload :Glif, "ucode/glyphs/last_resort/glif"
+      autoload :Svg, "ucode/glyphs/last_resort/svg"
+      autoload :Renderer, "ucode/glyphs/last_resort/renderer"
+      autoload :Writer, "ucode/glyphs/last_resort/writer"
+    end
+  end
+end

data/lib/ucode/glyphs/monolith_page_map.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "json"
+require "open3"
+
+module Ucode
+  module Glyphs
+    # Maps a Unicode block's first codepoint to its page range inside the
+    # monolith `CodeCharts.pdf` by parsing the PDF's bookmark outline and
+    # matching each bookmark title to a Block.name from `Blocks.txt`.
+    #
+    # Each chart cluster printed by the Unicode Consortium is a single
+    # bookmark entry:
+    #
+    #   BookmarkTitle: Greek and Coptic
+    #   BookmarkLevel: 1
+    #   BookmarkPageNumber: 415
+    #
+    # The cluster title usually equals a Block.name verbatim, but a few
+    # clusters carry a heading that prepends "C0 Controls and " /
+    # "C1 Controls and " to the block name. We resolve both forms.
+    #
+    # End-page of a cluster is one page before the next cluster's start
+    # page (last cluster's end-page is the PDF's last page).
+    #
+    # The map is cached as JSON at `data/codecharts_page_map.json` so
+    # we don't re-scan the 3,156-page monolith on every run.
+    class MonolithPageMap
+      BookmarkTitleRegex = /BookmarkTitle:\s*(.+)/.freeze
+      BookmarkPageRegex  = /BookmarkPageNumber:\s*(\d+)/.freeze
+      private_constant :BookmarkTitleRegex, :BookmarkPageRegex
+
+      # The Unicode charts print these multi-block clusters as a single
+      # chart page (the C0/C1 control chars are drawn alongside their
+      # block's other characters). Each cluster title maps to the single
+      # block it belongs to.
+      ClusterPrefixes = [
+        "C0 Controls and ",
+        "C1 Controls and ",
+      ].freeze
+      private_constant :ClusterPrefixes
+
+      MapEntry = Struct.new(:first_cp, :start_page, :end_page, keyword_init: true)
+
+      class << self
+        # Build the map by parsing the monolith's outline and matching
+        # each bookmark title to a Block.
+        #
+        # @param monolith_path [String, Pathname]
+        # @param blocks [Array<Ucode::Models::Block>] the parsed Blocks table
+        # @return [Hash{Integer => MapEntry}] keyed by block.range_first
+        def build(monolith_path:, blocks:)
+          name_to_first_cp = blocks.each_with_object({}) do |b, h|
+            h[b.name] = b.range_first
+          end
+          total_pages = page_count(monolith_path)
+          entries = parse_bookmarks(dump_bookmarks(monolith_path), name_to_first_cp)
+          attach_end_pages(entries, total_pages)
+          entries.each_with_object({}) do |e, h|
+            h[e.first_cp] = e
+          end
+        end
+
+        # Pure: parse a `pdftk dump_data` string into a list of
+        # MapEntry rows (without end_pages). Exposed for unit tests
+        # and any caller that already has the dump cached.
+        #
+        # @param dump [String] the raw `pdftk dump_data` output
+        # @param name_to_first_cp [Hash{String => Integer}]
+        # @return [Array<MapEntry>]
+        def parse_bookmarks(dump, name_to_first_cp)
+          entries = []
+          current_title = nil
+          dump.each_line do |line|
+            case line
+            when BookmarkTitleRegex
+              current_title = Regexp.last_match(1).strip
+            when BookmarkPageRegex
+              page = Regexp.last_match(1).to_i
+              cp = resolve_first_cp(current_title, name_to_first_cp)
+              entries << MapEntry.new(first_cp: cp, start_page: page) if cp
+              current_title = nil
+            end
+          end
+          entries.sort_by(&:start_page)
+        end
+
+        # Pure: attach end_pages by sorting entries and assigning each
+        # entry's end to one page before the next entry's start.
+        #
+        # @param entries [Array<MapEntry>]
+        # @param total_pages [Integer, nil] page count of the source PDF;
+        #   the last entry's end_page falls back to this when present.
+        # @return [Array<MapEntry>] the same entries, mutated with end_pages.
+        def attach_end_pages(entries, total_pages = nil)
+          sorted = entries.sort_by(&:start_page)
+          sorted.each_with_index do |entry, i|
+            next_entry = sorted[i + 1]
+            entry.end_page = next_entry ? next_entry.start_page - 1 : total_pages
+          end
+          sorted
+        end
+
+        # Load from cache, or build and cache.
+        # @param monolith_path [String, Pathname]
+        # @param blocks [Array<Ucode::Models::Block>]
+        # @param cache_path [String, Pathname, nil]
+        # @return [Hash{Integer => MapEntry}]
+        def load(monolith_path:, blocks:, cache_path: nil)
+          cache = cache_path && Pathname.new(cache_path)
+          if cache&.exist?
+            return load_from_json(cache.read)
+          end
+
+          map = build(monolith_path: monolith_path, blocks: blocks)
+          write_cache(map, cache) if cache
+          map
+        end
+
+        # Look up a block's page range by its first cp.
+        # @param map [Hash{Integer => MapEntry}]
+        # @param block_first_cp [Integer]
+        # @return [MapEntry, nil]
+        def range_for(map, block_first_cp)
+          map[block_first_cp]
+        end
+
+        # ---- I/O helpers (impure) --------------------------------------
+
+        def dump_bookmarks(monolith_path)
+          out, status = Open3.capture2e("pdftk", monolith_path.to_s, "dump_data")
+          return "" unless status.success?
+
+          out
+        end
+
+        def page_count(monolith_path)
+          out, status = Open3.capture2e("pdfinfo", monolith_path.to_s)
+          return nil unless status.success?
+
+          match = out.match(/^Pages:\s+(\d+)/)
+          match ? match[1].to_i : nil
+        end
+
+        private
+
+        def resolve_first_cp(title, name_to_first_cp)
+          return nil unless title
+
+          return name_to_first_cp[title] if name_to_first_cp.key?(title)
+
+          ClusterPrefixes.each do |prefix|
+            stripped = title.sub(/\A#{Regexp.escape(prefix)}/, "")
+            return name_to_first_cp[stripped] if name_to_first_cp.key?(stripped)
+          end
+
+          nil
+        end
+
+        def write_cache(map, cache_path)
+          payload = map.values.map { |e| { "first_cp" => e.first_cp,
+                                            "start_page" => e.start_page,
+                                            "end_page" => e.end_page } }
+          cache_path.dirname.mkpath
+          cache_path.write(JSON.pretty_generate(payload))
+        end
+
+        def load_from_json(json)
+          payload = JSON.parse(json)
+          payload.each_with_object({}) do |row, h|
+            entry = MapEntry.new(first_cp: row["first_cp"],
+                                 start_page: row["start_page"],
+                                 end_page: row["end_page"])
+            h[entry.first_cp] = entry
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/glyphs/mutool_renderer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "ucode/glyphs/page_renderer"
+
+module Ucode
+  module Glyphs
+    # `mutool draw` from MuPDF — typically the fastest and cleanest.
+    # Emits one `<svg>` per page with `<path>` vector data.
+    #
+    # Command: `mutool draw -F svg -o <out.svg> <in.pdf> <page>`
+    class MutoolRenderer < PageRenderer
+      class << self
+        def renderer_name
+          :mutool
+        end
+
+        def binary_name
+          :mutool
+        end
+
+        def build_command(pdf_path, page_num, out_path)
+          ["mutool", "draw", "-F", "svg", "-o", out_path.to_s,
+           pdf_path.to_s, page_num.to_s]
+        end
+      end
+    end
+  end
+end