fontisan 0.4.10 → 0.4.12

data/lib/fontisan/stitcher/partition_strategy/by_script.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    module PartitionStrategy
+      # Partition codepoints by Unicode script property.
+      #
+      # Each non-empty script becomes one or more partitions. Scripts
+      # that overflow +cap+ are chunked (Han has 80k+ codepoints) —
+      # chunks are named +:script_<name>_a+, +:script_<name>_b+, etc.,
+      # matching ByPlane's sub-split convention.
+      #
+      # Codepoints whose script is unknown (unassigned blocks) fall
+      # into +:script_other+. Codepoints in the +Common+ script
+      # (digits, punctuation shared across scripts) and +Inherited+
+      # script (combining marks) get their own buckets — they're
+      # typically useful as standalone subfonts.
+      #
+      # The script data is derived from {ByBlock::BLOCKS}: each Unicode
+      # block maps to exactly one primary script (with a few exceptions
+      # that we resolve explicitly). This keeps the data DRY — the
+      # authoritative block list lives in one place.
+      class ByScript < Base
+        # Maps each Unicode block label to its primary script.
+        # Block labels match ByBlock::BLOCKS keys.
+        #
+        # Special scripts:
+        #   - +:common+ — shared across scripts (digits, punctuation)
+        #   - +:inherited+ — combining marks that inherit the base char's script
+        #   - +:other+ — fallback for unlisted blocks
+        SCRIPT_OF_BLOCK = {
+          # Latin family
+          "Basic_Latin" => :common,
+          "Latin-1_Supplement" => :latin,
+          "Latin_Extended-A" => :latin,
+          "Latin_Extended-B" => :latin,
+          "Latin_Extended-C" => :latin,
+          "Latin_Extended-D" => :latin,
+          "Latin_Extended-E" => :latin,
+          "Latin_Extended-F" => :latin,
+          "Latin_Extended_Additional" => :latin,
+          "Phonetic_Extensions" => :latin,
+          "Phonetic_Extensions_Supplement" => :latin,
+          "Modifier_Tone_Letters" => :latin,
+          "Spacing_Modifier_Letters" => :common,
+          "Combining_Diacritical_Marks" => :inherited,
+          "Combining_Diacritical_Marks_Extended" => :inherited,
+          "Combining_Diacritical_Marks_Supplement" => :inherited,
+          "Combining_Diacritical_Marks_for_Symbols" => :inherited,
+          "Combining_Half_Marks" => :inherited,
+
+          # Greek
+          "Greek_and_Coptic" => :greek,
+          "Greek_Extended" => :greek,
+
+          # Cyrillic
+          "Cyrillic" => :cyrillic,
+          "Cyrillic_Supplement" => :cyrillic,
+          "Cyrillic_Extended-A" => :cyrillic,
+          "Cyrillic_Extended-B" => :cyrillic,
+          "Cyrillic_Extended-C" => :cyrillic,
+          "Cyrillic_Extended-D" => :cyrillic,
+
+          # Middle Eastern
+          "Armenian" => :armenian,
+          "Hebrew" => :hebrew,
+          "Arabic" => :arabic,
+          "Arabic_Supplement" => :arabic,
+          "Arabic_Extended-A" => :arabic,
+          "Arabic_Extended-B" => :arabic,
+          "Arabic_Extended-C" => :arabic,
+          "Arabic_Extended-D" => :arabic,
+          "Arabic_Presentation_Forms-A" => :arabic,
+          "Arabic_Presentation_Forms-B" => :arabic,
+          "Syriac" => :syriac,
+          "Syriac_Supplement" => :syriac,
+          "Thaana" => :thaana,
+          "Samaritan" => :samaritan,
+          "Mandaic" => :mandaic,
+
+          # Indic
+          "Devanagari" => :devanagari,
+          "Devanagari_Extended" => :devanagari,
+          "Bengali" => :bengali,
+          "Gurmukhi" => :gurmukhi,
+          "Gujarati" => :gujarati,
+          "Oriya" => :oriya,
+          "Tamil" => :tamil,
+          "Tamil_Supplement" => :tamil,
+          "Telugu" => :telugu,
+          "Kannada" => :kannada,
+          "Malayalam" => :malayalam,
+          "Sinhala" => :sinhala,
+          "Sinhala_Archaic_Numbers" => :sinhala,
+          "Vedic_Extensions" => :inherited,
+
+          # Southeast Asian
+          "Thai" => :thai,
+          "Lao" => :lao,
+          "Tibetan" => :tibetan,
+          "Myanmar" => :myanmar,
+          "Myanmar_Extended-A" => :myanmar,
+          "Myanmar_Extended-B" => :myanmar,
+          "Myanmar_Extended-C" => :myanmar,
+          "Khmer" => :khmer,
+          "Khmer_Symbols" => :khmer,
+          "Tagalog" => :tagalog,
+          "Hanunoo" => :hanunoo,
+          "Buhid" => :buhid,
+          "Tagbanwa" => :tagbanwa,
+
+          # Hangul
+          "Hangul_Jamo" => :hangul,
+          "Hangul_Compatibility_Jamo" => :hangul,
+          "Hangul_Jamo_Extended-A" => :hangul,
+          "Hangul_Jamo_Extended-B" => :hangul,
+          "Hangul_Syllables" => :hangul,
+
+          # CJK — Han + native Japanese / Korean
+          "CJK_Unified_Ideographs" => :han,
+          "CJK_Unified_Ideographs_Extension_A" => :han,
+          "CJK_Unified_Ideographs_Extension_B" => :han,
+          "CJK_Unified_Ideographs_Extension_C" => :han,
+          "CJK_Unified_Ideographs_Extension_D" => :han,
+          "CJK_Unified_Ideographs_Extension-E" => :han,
+          "CJK_Unified_Ideographs_Extension-F" => :han,
+          "CJK_Unified_Ideographs_Extension_G" => :han,
+          "CJK_Unified_Ideographs_Extension_H" => :han,
+          "CJK_Unified_Ideographs_Extension_I" => :han,
+          "CJK_Compatibility_Ideographs" => :han,
+          "CJK_Compatibility_Ideographs_Supplement" => :han,
+          "CJK_Radicals_Supplement" => :han,
+          "Kangxi_Radicals" => :han,
+          "CJK_Symbols_and_Punctuation" => :common,
+          "CJK_Compatibility" => :han,
+          "CJK_Compatibility_Forms" => :common,
+          "CJK_Strokes" => :han,
+          "Ideographic_Description_Characters" => :common,
+          "Enclosed_CJK_Letters_and_Months" => :common,
+          "Hiragana" => :hiragana,
+          "Katakana" => :katakana,
+          "Katakana_Phonetic_Extensions" => :katakana,
+          "Kana_Supplement" => :hiragana,
+          "Kana_Extended-A" => :hiragana,
+          "Kana_Extended-B" => :hiragana,
+          "Small_Kana_Extension" => :hiragana,
+          "Halfwidth_and_Fullwidth_Forms" => :common,
+          "Vertical_Forms" => :common,
+          "Ideographic_Symbols_and_Punctuation" => :common,
+
+          # Other scripts (single-block each)
+          "Ethiopic" => :ethiopic,
+          "Ethiopic_Supplement" => :ethiopic,
+          "Ethiopic_Extended" => :ethiopic,
+          "Ethiopic_Extended-A" => :ethiopic,
+          "Ethiopian_Extended-B" => :ethiopic,
+          "Cherokee" => :cherokee,
+          "Cherokee_Supplement" => :cherokee,
+          "Unified_Canadian_Aboriginal_Syllabics" => :canadian_aboriginal,
+          "Unified_Canadian_Aboriginal_Syllabics_Extended" => :canadian_aboriginal,
+          "Unified_Canadian_Aboriginal_Syllabics_Extended-A" => :canadian_aboriginal,
+          "Ogham" => :ogham,
+          "Runic" => :runic,
+          "Glagolitic" => :glagolitic,
+          "Glagolitic_Supplement" => :glagolitic,
+          "Tifinagh" => :tifinagh,
+          "Georgian" => :georgian,
+          "Georgian_Supplement" => :georgian,
+          "Georgian_Extended" => :georgian,
+          "Mongolian" => :mongolian,
+          "Mongolian_Supplement" => :mongolian,
+          "Limbu" => :limbu,
+          "Tai_Le" => :tai_le,
+          "New_Tai_Lue" => :new_tai_lue,
+          "Tai_Tham" => :tai_tham,
+          "Tai_Viet" => :tai_viet,
+          "Ol_Chiki" => :ol_chiki,
+          "Bopomofo" => :bopomofo,
+          "Bopomofo_Extended" => :bopomofo,
+          "Yi_Syllables" => :yi,
+          "Yi_Radicals" => :yi,
+          "Vai" => :vai,
+          "Bamum" => :bamum,
+          "Bamum_Supplement" => :bamum,
+          "Syloti_Nagri" => :syloti_nagri,
+          "Phags-pa" => :phags_pa,
+          "Saurashtra" => :saurashtra,
+          "Kayah_Li" => :kayah_li,
+          "Rejang" => :rejang,
+          "Javanese" => :javanese,
+          "Cham" => :cham,
+          "Lepcha" => :lepcha,
+          "Meetei_Mayek" => :meetei_mayek,
+          "Meetei_Mayek_Extensions" => :meetei_mayek,
+          "Lisu" => :lisu,
+          "Lisu_Supplement" => :lisu,
+          "Sundanese" => :sundanese,
+          "Sundanese_Supplement" => :sundanese,
+          "Batak" => :batak,
+          "Buginese" => :buginese,
+          "Ahom" => :ahom,
+          "Dogra" => :dogra,
+          "Tulu-Tigalari" => :tulu_tigalari,
+          "Grantha" => :grantha,
+          "Newa" => :newa,
+          "Tirhuta" => :tirhuta,
+          "Siddham" => :siddham,
+          "Modi" => :modi,
+          "Sharada" => :sharada,
+          "Takri" => :takri,
+          "Kaithi" => :kaithi,
+          "Mahajani" => :mahajani,
+          "Multani" => :multani,
+          "Khudawadi" => :khudawadi,
+          "Nandinagari" => :nandinagari,
+          "Nushu" => :nushu,
+          "Wancho" => :wancho,
+          "Toto" => :toto,
+          "Nag_Mundari" => :nag_mundari,
+
+          # Numerals / symbols (Common)
+          "Superscripts_and_Subscripts" => :common,
+          "Number_Forms" => :common,
+          "Currency_Symbols" => :common,
+          "Letterlike_Symbols" => :common,
+          "Arrows" => :common,
+          "Mathematical_Operators" => :common,
+          "Miscellaneous_Technical" => :common,
+          "Control_Pictures" => :common,
+          "Optical_Character_Recognition" => :common,
+          "Enclosed_Alphanumerics" => :common,
+          "Box_Drawing" => :common,
+          "Block_Elements" => :common,
+          "Geometric_Shapes" => :common,
+          "Miscellaneous_Symbols" => :common,
+          "Dingbats" => :common,
+          "Miscellaneous_Mathematical_Symbols-A" => :common,
+          "Miscellaneous_Mathematical_Symbols-B" => :common,
+          "Supplemental_Arrows-A" => :common,
+          "Supplemental_Arrows-B" => :common,
+          "Supplemental_Arrows-C" => :common,
+          "Supplemental_Mathematical_Operators" => :common,
+          "Miscellaneous_Symbols_and_Arrows" => :common,
+          "Braille_Patterns" => :braille,
+          "General_Punctuation" => :common,
+          "Supplemental_Punctuation" => :common,
+          "Alphabetic_Presentation_Forms" => :common,
+          "Specials" => :common,
+          "Variation_Selectors" => :inherited,
+          "Variation_Selectors_Supplement" => :inherited,
+          "Tags" => :common,
+        }.freeze
+
+        # @param cp_map [Hash{Integer=>Object}] codepoint → donor label
+        # @param cap [Integer] max codepoints per partition
+        # @return [Blueprint]
+        def call(cp_map, cap: DEFAULT_CAP)
+          grouped = group_by_script(cp_map)
+          partitions = []
+
+          grouped.each do |script, entries|
+            chunks(entries, cap).each_with_index do |chunk, idx|
+              partitions << Partition.new(
+                name: partition_name(script, idx),
+                cps: chunk.map(&:first),
+                donor_map: chunk.to_h,
+              )
+            end
+          end
+
+          Blueprint.new(partitions: partitions)
+        end
+
+        private
+
+        def group_by_script(cp_map)
+          cp_map.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(cp, label), h|
+            script = script_of_codepoint(cp)
+            h[script] << [cp, label]
+          end
+        end
+
+        def script_of_codepoint(cp)
+          block_label = ByBlock::BLOCKS.find { |_label, range| range.cover?(cp) }&.first
+          return :other unless block_label
+
+          SCRIPT_OF_BLOCK[block_label] || :other
+        end
+
+        def chunks(entries, cap)
+          entries.each_slice(cap).to_a
+        end
+
+        # First partition per script has no suffix; subsequent ones
+        # get _a, _b, ... matching ByPlane's sub-split convention.
+        def partition_name(script, idx)
+          return :"script_#{script}" if idx.zero?
+
+          suffix = ("a".ord + idx - 1).chr
+          :"script_#{script}_#{suffix}"
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/stitcher/partition_strategy.rb

@@ -17,6 +17,8 @@ module Fontisan
       autoload :Blueprint, "fontisan/stitcher/partition_strategy/blueprint"
       autoload :Partition, "fontisan/stitcher/partition_strategy/partition"
       autoload :ByPlane, "fontisan/stitcher/partition_strategy/by_plane"
+      autoload :ByBlock, "fontisan/stitcher/partition_strategy/by_block"
+      autoload :ByScript, "fontisan/stitcher/partition_strategy/by_script"
     end
   end
 end

data/lib/fontisan/stitcher/source.rb

@@ -336,10 +336,15 @@ module Fontisan
 
       # Apply a 2×3 affine matrix [a, b, c, d, e, f] to each point of
       # a simple component, appending the transformed contours.
-      #   x' = a*x + c*y + e
-      #   y' = b*x + d*y + f
+      # The math is delegated to +Transformation#apply+ so the
+      # affine-matrix logic lives in one place (DRY) — same code path
+      # the UFO Transformations filter uses.
       def flatten_simple_component(simple, ufo_glyph, matrix)
-        a, b, c, d, e, f = matrix
+        transform = Ufo::Transformation.new(
+          a: matrix[0], b: matrix[1],
+          c: matrix[2], d: matrix[3],
+          e: matrix[4], f: matrix[5]
+        )
         num_contours = simple.end_pts_of_contours&.size || 0
         return if num_contours.zero?
 
@@ -350,13 +355,12 @@ module Fontisan
           ufo_points = points.map do |pt|
             x = (pt[:x] || pt["x"]).to_f
             y = (pt[:y] || pt["y"]).to_f
-            tx = a * x + c * y + e
-            ty = b * x + d * y + f
+            tx, ty = transform.apply(x, y)
             on_curve = pt[:on_curve].nil? || pt[:on_curve]
             type = on_curve ? "line" : "offcurve"
-            Fontisan::Ufo::Point.new(x: tx, y: ty, type: type)
+            Ufo::Point.new(x: tx, y: ty, type: type)
           end
-          ufo_glyph.add_contour(Fontisan::Ufo::Contour.new(ufo_points))
+          ufo_glyph.add_contour(Ufo::Contour.new(ufo_points))
         end
       end
 

data/lib/fontisan/subset/table_subsetter.rb

@@ -56,6 +56,8 @@ module Fontisan
         @options = options
         @glyf_data = nil
         @loca_offsets = nil
+        @subset_bbox = nil      # [xMin, yMin, xMax, yMax] over actual subset glyphs
+        @subset_max_advance = 0 # largest advanceWidth in subset hmtx
       end
 
       # Subset a table by tag
@@ -110,10 +112,12 @@ module Fontisan
         data
       end
 
-      # Subset hhea table (update numberOfHMetrics)
+      # Subset hhea table (update numberOfHMetrics + advanceWidthMax)
       #
-      # Updates the numberOfHMetrics field to reflect the number of
-      # horizontal metrics in the subset font.
+      # Updates numberOfHMetrics to reflect the subset's glyph count and
+      # recomputes advanceWidthMax from the subset's actual hmtx. The
+      # source TTC's advanceWidthMax covers every donor font and is far
+      # larger than any per-block subset needs.
       #
       # @param table [Hhea] Parsed hhea table
       # @param hmtx [Hmtx, nil] Optional parsed hmtx table (for calculating metrics)
@@ -128,9 +132,18 @@ module Fontisan
                               calculate_number_of_h_metrics
                             end
 
-        # Update numberOfHMetrics field (at offset 34, uint16)
+        # numberOfHMetrics at offset 34 (uint16)
         data[34, 2] = [new_num_h_metrics].pack("n")
 
+        # advanceWidthMax at offset 10 (uint16). Recompute from subset
+        # hmtx so a per-block subset doesn't keep the source TTC's
+        # max (which can be 4x larger than any glyph in the subset).
+        # Tables are processed alphabetically (hhea before hmtx), so
+        # we read hmtx directly here rather than relying on a cached
+        # value from subset_hmtx.
+        new_max = compute_subset_max_advance
+        data[10, 2] = [new_max].pack("n") if new_max.positive?
+
         data
       end
 
@@ -152,14 +165,18 @@ module Fontisan
         # Build new hmtx data
         data = String.new(encoding: Encoding::BINARY)
 
+        max_advance = 0
         mapping.old_ids.each do |old_id|
           metric = table.metric_for(old_id)
           next unless metric
 
-          data << [metric[:advance_width]].pack("n")
+          advance = metric[:advance_width]
+          max_advance = advance if advance && advance > max_advance
+          data << [advance].pack("n")
           data << [metric[:lsb]].pack("n")
         end
 
+        @subset_max_advance = max_advance
         data
       end
 
@@ -264,8 +281,32 @@ module Fontisan
       #
       # @param table [Head] Parsed head table
       # @return [String] Binary data of subset head table
+      # Subset head table (recompute bbox from actual subset glyphs)
+      #
+      # The source TTC's head.xMin/yMin/xMax/yMax covers every donor
+      # font in the collection — far larger than any per-block subset.
+      # Browsers and layout engines use head bbox (plus hhea + OS/2)
+      # to compute line height and clip text; a too-large bbox makes
+      # glyphs render at the wrong visual size.
+      #
+      # @param _table [Head] Parsed head table (unused; we re-serialize
+      #   directly from font.table_data so we don't lose other fields)
+      # @return [String] Binary data of subset head table
       def subset_head(_table)
-        font.table_data["head"]
+        # Trigger glyf build (which populates @subset_bbox) if not done.
+        glyf = font.table("glyf")
+        build_glyf_and_loca(glyf) unless @glyf_data
+
+        data = font.table_data["head"].dup
+
+        if @subset_bbox
+          x_min, y_min, x_max, y_max = @subset_bbox
+          # head layout: xMin at offset 36, yMin 38, xMax 40, yMax 42
+          # (each int16, big-endian, signed)
+          data[36, 8] = [x_min, y_min, x_max, y_max].pack("n4")
+        end
+
+        data
       end
 
       # Subset OS/2 table (optionally prune Unicode ranges)
@@ -295,6 +336,32 @@ module Fontisan
         mapping.size
       end
 
+      # Compute the largest advanceWidth across all subset glyphs by
+      # reading the source hmtx directly. Called from subset_hhea
+      # because hhea is processed before hmtx (alphabetical order).
+      #
+      # @return [Integer] max advanceWidth, or 0 if no metrics found
+      def compute_subset_max_advance
+        hmtx = font.table("hmtx")
+        return 0 unless hmtx
+
+        unless hmtx.parsed?
+          hhea = font.table("hhea")
+          maxp = font.table("maxp")
+          hmtx.parse_with_context(hhea.number_of_h_metrics, maxp.num_glyphs)
+        end
+
+        max_advance = 0
+        mapping.old_ids.each do |old_id|
+          metric = hmtx.metric_for(old_id)
+          next unless metric
+
+          advance = metric[:advance_width]
+          max_advance = advance if advance && advance > max_advance
+        end
+        max_advance
+      end
+
       # Build glyf and loca tables together
       #
       # This method extracts glyph data for all glyphs in the mapping,
@@ -318,6 +385,17 @@ module Fontisan
         @loca_offsets = []
         current_offset = 0
 
+        # Track union bbox across all subset glyphs. Glyph binary layout:
+        #   int16 numberOfContours (offset 0)
+        #   int16 xMin (offset 2)
+        #   int16 yMin (offset 4)
+        #   int16 xMax (offset 6)
+        #   int16 yMax (offset 8)
+        bbox_x_min = 1 << 30
+        bbox_y_min = 1 << 30
+        bbox_x_max = -(1 << 30)
+        bbox_y_max = -(1 << 30)
+
         # Process glyphs in mapping order
         mapping.old_ids.each do |old_id|
           @loca_offsets << current_offset
@@ -334,6 +412,21 @@ module Fontisan
           # Extract glyph data
           glyph_data = glyf_table.raw_data[offset, size]
 
+          # Update bbox union. Each glyph has at least 10 bytes of
+          # header (numberOfContours + 4 int16 bbox fields).
+          if glyph_data.bytesize >= 10
+            _n, gx_min, gy_min, gx_max, gy_max = glyph_data[0, 10].unpack("n5")
+            # Treat as signed int16
+            gx_min = (gx_min ^ 0x8000) - 0x8000
+            gy_min = (gy_min ^ 0x8000) - 0x8000
+            gx_max = (gx_max ^ 0x8000) - 0x8000
+            gy_max = (gy_max ^ 0x8000) - 0x8000
+            bbox_x_min = gx_min if gx_min < bbox_x_min
+            bbox_y_min = gy_min if gy_min < bbox_y_min
+            bbox_x_max = gx_max if gx_max > bbox_x_max
+            bbox_y_max = gy_max if gy_max > bbox_y_max
+          end
+
           # Check if compound glyph and remap components
           if compound_glyph?(glyph_data)
             glyph_data = remap_compound_glyph(glyph_data)
@@ -346,6 +439,11 @@ module Fontisan
 
         # Add final offset
         @loca_offsets << current_offset
+
+        # Stash union bbox if we saw at least one non-empty glyph.
+        return if bbox_x_min > bbox_x_max
+
+        @subset_bbox = [bbox_x_min, bbox_y_min, bbox_x_max, bbox_y_max]
       end
 
       # Check if glyph data represents a compound glyph
@@ -417,12 +515,130 @@ module Fontisan
       # Creates a minimal cmap table with format 4 subtable for BMP
       # and format 12 for supplementary planes if needed.
       #
-      # @param mappings [Hash<Integer, Integer>] Char code => glyph ID
+      # @param mappings [Hash<Integer, Integer>] Char code => new glyph ID
       # @return [String] Binary cmap data
-      def build_cmap_binary(_mappings)
-        # For now, pass through original cmap
-        # TODO: Implement proper cmap building
-        font.table_data["cmap"]
+      def build_cmap_binary(mappings)
+        # Edge case: empty mappings (e.g., block with no covered chars).
+        # Emit a minimal valid cmap with one format 4 subtable mapping
+        # only U+0000 → .notdef so the table isn't empty.
+        mappings = { 0 => 0 } if mappings.empty?
+
+        bmp = mappings.select { |cp, _| cp <= 0xFFFF }
+        supp = mappings.select { |cp, _| cp > 0xFFFF }
+
+        subtables = []
+        records = [] # [platform_id, encoding_id, subtable_index]
+
+        unless bmp.empty?
+          subtables << build_cmap_format_4(bmp)
+          idx = subtables.size - 1
+          records << [3, 1, idx] # Windows BMP
+          records << [0, 3, idx] # Unicode BMP
+        end
+
+        unless supp.empty?
+          # Format 12 covers both BMP and supplementary — include all
+          # mappings so a single subtable covers the full range.
+          subtables << build_cmap_format_12(mappings)
+          idx = subtables.size - 1
+          records << [3, 10, idx] # Windows UCS-4
+          records << [0, 4, idx]  # Unicode full
+        end
+
+        # Header: version (uint16) + numTables (uint16)
+        num_tables = records.size
+        header = [0, num_tables].pack("nn")
+
+        # Encoding records start immediately after the header.
+        # Each record is 8 bytes; subtables follow.
+        subtable_base = 4 + (8 * num_tables)
+
+        offsets = []
+        running = subtable_base
+        subtables.each do |st|
+          offsets << running
+          running += st.bytesize
+        end
+
+        record_bytes = +""
+        records.each do |pid, eid, idx|
+          record_bytes << [pid, eid, offsets[idx]].pack("nnN")
+        end
+
+        header + record_bytes + subtables.join
+      end
+
+      # Format 4 subtable: segment-mapping with idDelta, suitable for
+      # BMP codepoints (U+0000..U+FFFF). Builds compact segments where
+      # consecutive codepoints map to consecutive glyph IDs.
+      def build_cmap_format_4(bmp_mappings)
+        segments = coalesce_segments(bmp_mappings)
+        # Mandatory final segment: U+FFFF → gid 0 (per OpenType spec).
+        segments << { start_cp: 0xFFFF, end_cp: 0xFFFF, start_gid: 0 }
+
+        seg_count = segments.size
+        seg_count_x2 = seg_count * 2
+        search_range = 2**Math.log2(seg_count).floor * 2
+        search_range = 2 if search_range < 2
+        entry_selector = Math.log2(search_range / 2).to_i
+        range_shift = seg_count_x2 - search_range
+
+        end_codes = segments.map { |s| s[:end_cp] }
+        start_codes = segments.map { |s| s[:start_cp] }
+        # idDelta is int16 stored as uint16 (two's complement). For a
+        # sequential segment, idDelta = (start_gid - start_cp) & 0xFFFF.
+        id_deltas = segments.map { |s| (s[:start_gid] - s[:start_cp]) & 0xFFFF }
+        id_range_offsets = [0] * seg_count
+
+        subtable = +""
+        subtable << [4, 0, 0, seg_count_x2,
+                     search_range, entry_selector, range_shift].pack("n*")
+        subtable << end_codes.pack("n*")
+        subtable << [0].pack("n") # reservedPad
+        subtable << start_codes.pack("n*")
+        subtable << id_deltas.pack("n*")
+        subtable << id_range_offsets.pack("n*")
+
+        # Patch the length field (was placeholder 0).
+        subtable[2, 2] = [subtable.bytesize].pack("n")
+        subtable
+      end
+
+      # Format 12 subtable: segmented coverage for full Unicode range.
+      # Simpler than format 4 — just (start_char, end_char, start_gid)
+      # triples with no delta/offset indirection.
+      def build_cmap_format_12(all_mappings)
+        groups = coalesce_segments(all_mappings)
+        num_groups = groups.size
+
+        subtable = +""
+        subtable << [12, 0, 0, 0, num_groups].pack("nnNNN")
+        groups.each do |g|
+          subtable << [g[:start_cp], g[:end_cp], g[:start_gid]].pack("NNN")
+        end
+
+        # Patch the length field (was placeholder 0). Total length is
+        # 16-byte header + 12 bytes per group.
+        subtable[4, 4] = [subtable.bytesize].pack("N")
+        subtable
+      end
+
+      # Group codepoints into consecutive runs where both codepoint AND
+      # glyph ID are sequential. Each run becomes one segment/group.
+      def coalesce_segments(mappings)
+        sorted = mappings.sort_by { |cp, _| cp }
+        segments = []
+        current = nil
+        sorted.each do |cp, gid|
+          if current && cp == current[:end_cp] + 1 && gid == current[:start_gid] + (cp - current[:start_cp])
+            current[:end_cp] = cp
+          else
+            segments << current if current
+            current = { start_cp: cp, end_cp: cp, start_gid: gid }
+          end
+        end
+        segments << current if current
+        segments
       end
 
       # Build post table version 3.0 (no glyph names)