fontisan 0.4.9 → 0.4.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38b49343b74d1876d57ec13992fc49fdc2879a44d1f0fe3c6529bd3a2f8f7a75
-  data.tar.gz: cc69156566e86294177d9046f39ebde8334f87807da38a7a5dd83ddd2eea8247
+  metadata.gz: 797250db52b46986a1458fd680d2c2f2eab6896ba1bcf617ba0d74622ce7ff51
+  data.tar.gz: 81cf20d3aff4f40b33e0fec8cc8de359a1a4acf139d14fe75ec3a4fc839ac827
 SHA512:
-  metadata.gz: 2822ae02861c4183bbd42ded8005fa17d28d59175155767413f94b4400faaf28fb61dad38736f3fcd11235746e1b254151c8e8918480b5ccb146882742c3ec99
-  data.tar.gz: eefb0dbf8e3360e7b8aeb89dfcfbf62425c255075ee1a3d2c030cd2551f90f08d980f7ea7b8c56c382b0a1cb69933654a57fc4e57d069ebe6809ace84e7d0b42
+  metadata.gz: dc92df9fbb61326d199f51ceda010e8f990cd109355679d463066e0f590a461e71241239b6b90f3a1acf5832362fba778d51833d24eb01c46b42b95c488c3550
+  data.tar.gz: c331cceb05fd29864a85e4e7d7dca99aa96c9c2ef152c3e877842aaffd0a82d1ad46e6770d5e80d3799bb67a905306a1eb6e5b4d18d03f5c8a02072c030c33f8

data/docs/STITCHER_GUIDE.adoc

@@ -165,8 +165,18 @@ must either raise the cap, drop codepoints, or switch to a format
 with a higher glyph limit.
 
 The Unicode plane metadata used by ByPlane lives in
-`Fontisan::Unicode::Plane` (`Plane.of(cp)`, `Plane.label(n)`,
-`Plane::LARGE_CJK_BLOCKS`).
+`Fontisan::Unicode::Plane` (`Plane.of(cp)`, `Plane.label(n)`).
+
+The sub-plane block boundaries used for sub-splitting live on ByPlane
+itself:
+
+* `ByPlane::ATOMIC_BLOCKS` — five SIP CJK extension blocks that cannot
+  be sub-split; raise if one alone exceeds `cap`.
+* `ByPlane::CARVE_OUT_BLOCKS` — BMP-resident blocks (CJK Unified
+  Ideographs, Hangul Syllables) that get their own partition bucket
+  when BMP overflows `cap`; chunkable, never raised.
+* `ByPlane::RECOGNIZED_BLOCKS` — union of the two; the lookup table
+  the bucketing pass walks.
 
 === Partition / Blueprint
 

data/lib/fontisan/converters/svg_generator.rb

@@ -145,7 +145,7 @@ palette_index: 0)
       #
       # @param font [TrueTypeFont, OpenTypeFont] Source font
       # @param options [Hash] Extraction options
-      # @return [Hash] Glyph data map (glyph_id => {outline, unicode, name, advance})
+      # @return [Hash] Glyph data map (glyph_id => {outline, codepoints, name, advance})
       def extract_glyph_data(font, options = {})
         extractor = OutlineExtractor.new(font)
         cmap = font.table("cmap")
@@ -157,33 +157,20 @@ palette_index: 0)
         num_glyphs = maxp&.num_glyphs || 0
         max_glyphs = options[:max_glyphs] || num_glyphs
 
-        # Get unicode mappings
-        unicode_map = build_unicode_map(cmap)
+        gid_to_codepoints = build_glyph_to_codepoints(cmap)
+        glyph_names = post&.glyph_names || []
 
-        # Extract specified or all glyphs
         glyph_ids = options[:glyph_ids] || (0...num_glyphs).to_a
         glyph_ids = glyph_ids.take(max_glyphs) if max_glyphs
 
         glyph_ids.each do |glyph_id|
           next if glyph_id >= num_glyphs
 
-          # Extract outline
-          outline = extractor.extract(glyph_id)
-
-          # Get advance width
-          advance = extract_advance_width(hmtx, glyph_id)
-
-          # Get unicode character
-          unicode = unicode_map[glyph_id]
-
-          # Get glyph name
-          glyph_name = extract_glyph_name(post, glyph_id)
-
           glyph_data[glyph_id] = {
-            outline: outline,
-            unicode: unicode,
-            name: glyph_name,
-            advance: advance,
+            outline: extractor.extract(glyph_id),
+            codepoints: gid_to_codepoints[glyph_id] || [],
+            name: glyph_name_for(glyph_names, glyph_id),
+            advance: extract_advance_width(hmtx, glyph_id),
           }
         rescue StandardError => e
           warn "Failed to extract glyph #{glyph_id}: #{e.message}"
@@ -193,61 +180,38 @@ palette_index: 0)
         glyph_data
       end
 
-      # Build unicode to glyph ID map from cmap table
+      # Build reverse cmap: glyph_id => [codepoint, ...].
       #
-      # @param cmap [Tables::Cmap, nil] Cmap table
-      # @return [Hash<Integer, String>] Map of glyph_id to unicode character
-      def build_unicode_map(cmap)
+      # A glyph can be referenced by multiple codepoints (e.g. space
+      # and non-breaking space might share a glyph). Uses
+      # +cmap.unicode_mappings+ directly — that is the canonical
+      # {codepoint => gid} hash.
+      #
+      # @param cmap [Tables::Cmap, nil]
+      # @return [Hash<Integer, Array<Integer>>]
+      def build_glyph_to_codepoints(cmap)
         return {} unless cmap
 
-        unicode_map = {}
-
-        # Get best cmap subtable (prefer Unicode BMP or full)
-        subtable = find_best_cmap_subtable(cmap)
-        return {} unless subtable
-
-        # Build reverse map: glyph_id => unicode
-        subtable.each do |code_point, glyph_id|
-          # Store first unicode for each glyph
-          next if unicode_map[glyph_id]
-
-          unicode_map[glyph_id] = [code_point].pack("U")
-        rescue StandardError
-          # Skip invalid code points
-          next
+        cmap.unicode_mappings.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(cp, gid), h|
+          h[gid] << cp
         end
-
-        unicode_map
       rescue StandardError => e
-        warn "Failed to build unicode map: #{e.message}"
+        warn "Failed to build glyph to codepoints map: #{e.message}"
         {}
       end
 
-      # Find best cmap subtable for unicode mapping
+      # Look up glyph name from the post table's per-gid name array.
       #
-      # @param cmap [Tables::Cmap] Cmap table
-      # @return [Hash, nil] Subtable or nil
-      def find_best_cmap_subtable(cmap)
-        # Try Unicode BMP (platform 3, encoding 1) - Windows Unicode BMP
-        subtable = cmap.subtable(3, 1)
-        return subtable if subtable
-
-        # Try Unicode full (platform 3, encoding 10) - Windows Unicode full
-        subtable = cmap.subtable(3, 10)
-        return subtable if subtable
-
-        # Try Unicode (platform 0, encoding 3) - Unicode 2.0+ BMP
-        subtable = cmap.subtable(0, 3)
-        return subtable if subtable
-
-        # Try Unicode (platform 0, encoding 4) - Unicode 2.0+ full
-        subtable = cmap.subtable(0, 4)
-        return subtable if subtable
-
-        # Fallback to any available subtable
-        cmap.subtables.first
-      rescue StandardError
-        nil
+      # Falls back to +"gidN"+ when the post table has no name for the
+      # given gid (post version 3.0 fonts omit per-glyph names, and
+      # version 2.0 may have gaps). Always returns a non-nil string so
+      # the SVG <glyph> element carries a useful glyph-name attribute.
+      #
+      # @param glyph_names [Array<String>] post.glyph_names
+      # @param glyph_id [Integer]
+      # @return [String]
+      def glyph_name_for(glyph_names, glyph_id)
+        glyph_names[glyph_id] || "gid#{glyph_id}"
       end
 
       # Extract advance width for glyph
@@ -265,22 +229,6 @@ palette_index: 0)
       rescue StandardError
         0
       end
-
-      # Extract glyph name from post table
-      #
-      # @param post [Tables::Post, nil] Post table
-      # @param glyph_id [Integer] Glyph ID
-      # @return [String, nil] Glyph name or nil
-      def extract_glyph_name(post, glyph_id)
-        return nil unless post
-
-        name = post.glyph_name_for(glyph_id)
-        return nil if name.nil? || name.empty?
-
-        name
-      rescue StandardError
-        nil
-      end
     end
   end
 end

data/lib/fontisan/sfnt_font.rb

@@ -59,8 +59,16 @@ module Fontisan
       header.num_tables
     }
 
-    # Table data is stored separately since it's at variable offsets
-    attr_accessor :table_data
+    # Table data is stored separately since it's at variable offsets.
+    # The setter normalizes all keys to UTF-8 so Hash lookups don't
+    # silently miss due to encoding mismatch — BinData-derived tag
+    # strings are ASCII-8BIT, literals callers pass are usually UTF-8,
+    # and String#eql? is encoding-sensitive.
+    attr_reader :table_data
+
+    def table_data=(hash)
+      @table_data = hash.transform_keys { |tag| normalize_tag(tag) }
+    end
 
     # Parsed table instances cache
     attr_accessor :parsed_tables
@@ -470,6 +478,8 @@ module Fontisan
     # @return [Tables::*, nil] Parsed table object or nil if not found
     # @raise [ArgumentError] if table is not available in current loading mode
     def table(tag)
+      tag = normalize_tag(tag)
+
       # Check mode restrictions
       unless table_available?(tag)
         if has_table?(tag)

data/lib/fontisan/stitcher/format_metadata.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    # Immutable metadata about a stitcher output format. Single source
+    # of truth for "given a format symbol, what compiler / collection
+    # format / file extension does it use?". Adding a new format =
+    # adding a +when+ branch in {resolve}; no other site in Stitcher
+    # needs to know the mapping.
+    class FormatMetadata
+      attr_reader :name, :compiler_class, :collection_format, :extension
+
+      # @param name [Symbol] canonical format name (:ttf, :otf, :otf2)
+      # @param compiler_class [Class] the +Ufo::Compile::*Compiler+ that
+      #   compiles a +Ufo::Font+ target into the format's binary
+      # @param collection_format [Symbol] :ttc or :otc — the
+      #   +Collection::Builder+ format used when packing multiple
+      #   subfonts of this format into a collection
+      # @param extension [String] file extension including the dot
+      def initialize(name:, compiler_class:, collection_format:, extension:)
+        @name = name
+        @compiler_class = compiler_class
+        @collection_format = collection_format
+        @extension = extension
+      end
+
+      # Resolve a format name (Symbol or String) to its metadata.
+      # Constants are referenced inside +when+ branches so autoload
+      # fires only for the requested format, not all of them.
+      #
+      # @param name [Symbol, String]
+      # @raise [ArgumentError] if +name+ is not a known stitcher format
+      # @return [FormatMetadata]
+      def self.resolve(name)
+        case name.to_sym
+        when :ttf
+          new(name: :ttf, compiler_class: Ufo::Compile::TtfCompiler,
+              collection_format: :ttc, extension: ".ttf")
+        when :otf
+          new(name: :otf, compiler_class: Ufo::Compile::OtfCompiler,
+              collection_format: :otc, extension: ".otf")
+        when :otf2
+          new(name: :otf2, compiler_class: Ufo::Compile::Otf2Compiler,
+              collection_format: :otc, extension: ".otf")
+        else
+          raise ArgumentError, "unknown format: #{name.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -6,9 +6,38 @@ module Fontisan
       # Abstract base. Concrete partitioners (ByPlane, ByBlock, …)
       # implement {#call} and return a {Blueprint}.
       class Base
-        # Default cap: 65,535 − .notdef − safety margin. Matches the
-        # Stitcher's own +GlyphLimit+ cap for TTF.
-        DEFAULT_CAP = 65_484
+        # Glyph-cap headroom below the format's hard cap
+        # (GlyphLimit::TTF_GLYPH_CAP / OTF_GLYPH_CAP = 65,535). The
+        # partitioner must keep each partition's *codepoint* count low
+        # enough that compile-time *glyph* expansion still fits under
+        # the hard cap.
+        #
+        # Reserved slots:
+        #   - .notdef (1 slot, mandated by OpenType — every font has it
+        #     at GID 0 even when no codepoint binds to it)
+        #   - composite expansion: compiling adds composites (ligatures,
+        #     decomposable glyphs, variant attachments) on top of the
+        #     source codepoint count. Empirically ~5% of typical BMP
+        #     size for CJK-heavy fonts (≈2,500 composites on a 50k-cp
+        #     BMP font). 5,534 slots covers that with margin.
+        NOTDEF_RESERVED = 1
+        COMPOSITE_HEADROOM = 5_534
+
+        # Derive the partition cap from a format's hard glyph limit.
+        # Mirrors GlyphLimit so a future bump (e.g. CFF2 card24 INDEX
+        # counts) cascades automatically — no second magic number to
+        # keep in sync.
+        #
+        # @param format [Symbol] :ttf, :otf, or :otf2
+        # @return [Integer]
+        def self.cap_for(format)
+          GlyphLimit.for_format(format) - NOTDEF_RESERVED - COMPOSITE_HEADROOM
+        end
+
+        # Default cap for the most common format (TTF, where the glyph
+        # cap equals 65,535). Use {.cap_for} when partitioning for a
+        # different format.
+        DEFAULT_CAP = cap_for(:ttf)
 
         # @param cp_map [Hash{Integer=>Object}] codepoint → donor label
         # @param cap [Integer] max codepoints per partition

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

@@ -8,15 +8,47 @@ module Fontisan
       # For each plane with codepoints:
       #   - if the count fits under +cap+, emit one partition named
       #     +:plane_<n>+ (e.g. +:plane_0+, +:plane_2+);
-      #   - otherwise sub-split using the large CJK extension block
-      #     boundaries, naming partitions +:plane_<n>_a+, +:plane_<n>_b+,
-      #     and so on.
+      #   - otherwise sub-split along the recognized sub-plane block
+      #     boundaries (+RECOGNIZED_BLOCKS+), naming partitions
+      #     +:plane_<n>_a+, +:plane_<n>_b+, and so on.
       #
-      # If a single CJK extension block alone exceeds +cap+, raises
-      # {Fontisan::GlyphLimitExceededError} — the partitioner cannot
+      # If a single +ATOMIC_BLOCKS+ entry alone exceeds +cap+, raises
+      # {Fontisan::PartitionCapExceededError} — the partitioner cannot
       # satisfy the cap and the caller must use a smaller cap, split
       # manually, or switch to a format with a higher glyph limit.
+      # +CARVE_OUT_BLOCKS+ entries are chunkable and will be sliced
+      # like +:other+ if they exceed +cap+.
       class ByPlane < Base
+        # Atomic sub-plane blocks: cannot be sub-split further because
+        # no finer-grained Unicode boundary exists inside them. If one
+        # alone exceeds +cap+, raise PartitionCapExceededError.
+        #
+        # Labels follow the Unicode Blocks.txt block names with spaces
+        # replaced by underscores.
+        ATOMIC_BLOCKS = {
+          "CJK_Ext_B" => 0x2A700..0x2B73F,
+          "CJK_Ext_C" => 0x2B740..0x2B81F,
+          "CJK_Ext_D" => 0x2B820..0x2CEAF,
+          "CJK_Ext_E" => 0x2CEB0..0x2EBEF,
+          "CJK_Ext_F" => 0x2EBF0..0x2EE5F,
+        }.freeze
+
+        # Carve-out boundaries: sub-plane regions large enough to
+        # warrant their own partition bucket when a plane overflows
+        # +cap+. Unlike atomic blocks, these are chunkable — if one
+        # alone exceeds +cap+, it gets sliced into +cap+-sized chunks
+        # like +:other+ does, never raised.
+        CARVE_OUT_BLOCKS = {
+          "CJK_Unified_Ideographs" => 0x4E00..0x9FFF,
+          "Hangul_Syllables" => 0xAC00..0xD7AF,
+        }.freeze
+
+        # Every codepoint range recognized as a distinct sub-plane
+        # bucket. Atomic blocks first, then carve-out blocks. Used by
+        # the bucketing pass to decide what gets its own partition vs.
+        # falls into +:other+.
+        RECOGNIZED_BLOCKS = ATOMIC_BLOCKS.merge(CARVE_OUT_BLOCKS).freeze
+
         # @param cp_map [Hash{Integer=>Object}] codepoint → donor label
         # @param cap [Integer] max codepoints per partition
         # @return [Blueprint]
@@ -50,20 +82,21 @@ module Fontisan
           )
         end
 
-        # When a plane overflows +cap+, carve it along the large CJK
-        # extension block boundaries. The +:other+ bucket (everything
-        # outside the known mega-blocks) is split into chunks of +cap+,
-        # while each known large block becomes one partition atomically —
-        # if a single block alone exceeds +cap+, we cannot sub-split it
-        # (its codepoints are contiguous and we don't have finer-grained
-        # boundaries to use), so raise.
+        # When a plane overflows +cap+, carve it along the recognized
+        # sub-plane block boundaries. The +:other+ bucket (everything
+        # outside +RECOGNIZED_BLOCKS+) and any +CARVE_OUT_BLOCKS+ entries
+        # are split into chunks of +cap+. +ATOMIC_BLOCKS+ entries become
+        # one partition atomically — if a single atomic block alone
+        # exceeds +cap+, we cannot sub-split it (its codepoints are
+        # contiguous and we don't have finer-grained boundaries to use),
+        # so raise.
         def sub_split_by_block(plane_num, entries, cap)
-          buckets = bucket_by_large_block(entries)
+          buckets = bucket_by_recognized_block(entries)
           partitions = []
           suffix = "a"
 
           buckets.each do |label, bucket_entries|
-            if large_block?(label) && bucket_entries.size > cap
+            if atomic_block?(label) && bucket_entries.size > cap
               raise PartitionCapExceededError.new(
                 block_label: label,
                 actual: bucket_entries.size,
@@ -83,8 +116,8 @@ module Fontisan
           partitions
         end
 
-        def large_block?(label)
-          Fontisan::Unicode::Plane::LARGE_CJK_BLOCKS.key?(label)
+        def atomic_block?(label)
+          ATOMIC_BLOCKS.key?(label)
         end
 
         # Split +entries+ into sub-arrays of at most +cap+ each.
@@ -92,17 +125,16 @@ module Fontisan
           entries.each_slice(cap).to_a
         end
 
-        # Bucket entries by which large CJK block (or :other) they fall
-        # into. Entries outside any known large block go into :other,
-        # which is then packed into its own partition(s).
-        def bucket_by_large_block(entries)
+        # Bucket entries by which recognized sub-plane block (or :other)
+        # they fall into. Entries outside any known block go into :other,
+        # which is then packed into its own partition(s). Order: :other
+        # first if non-empty, then recognized blocks in declaration order.
+        def bucket_by_recognized_block(entries)
           buckets = { other: [] }
-          Fontisan::Unicode::Plane::LARGE_CJK_BLOCKS.each_key do |label|
-            buckets[label] = []
-          end
+          RECOGNIZED_BLOCKS.each_key { |label| buckets[label] = [] }
 
           entries.each do |cp, label|
-            block = find_large_block(cp)
+            block = find_recognized_block(cp)
             if block
               buckets[block] << [cp, label]
             else
@@ -110,18 +142,16 @@ module Fontisan
             end
           end
 
-          # Drop empty buckets; preserve order (other first if non-empty,
-          # then CJK blocks in declaration order).
           ordered = []
           ordered << [:other, buckets[:other]] unless buckets[:other].empty?
-          Fontisan::Unicode::Plane::LARGE_CJK_BLOCKS.each_key do |label|
+          RECOGNIZED_BLOCKS.each_key do |label|
             ordered << [label, buckets[label]] unless buckets[label].empty?
           end
           ordered
         end
 
-        def find_large_block(codepoint)
-          Fontisan::Unicode::Plane::LARGE_CJK_BLOCKS.find do |_label, range|
+        def find_recognized_block(codepoint)
+          RECOGNIZED_BLOCKS.find do |_label, range|
             range.include?(codepoint)
           end&.first
         end

data/lib/fontisan/stitcher/source.rb

@@ -15,14 +15,49 @@ module Fontisan
     # #bitmap_mode. When a source is :cbdt, the Stitcher propagates
     # the raw CBDT/CBLC tables into the output instead of extracting
     # outlines. The glyph data lives in the bitmap tables, not in glyf.
+    #
+    # = Codepoint remap
+    #
+    # Some donor fonts ship glyphs at non-canonical codepoints — a
+    # keyboard-mapped font whose "A" is at U+0041, or a PUA-allocated
+    # pre-Unicode font. Pass a +remap:+ hash at construction to expose
+    # those glyphs at their canonical codepoints without mutating the
+    # donor font's cmap:
+    #
+    #   Source.new(font, remap: { 0x41 => 0x11DB0 })
+    #
+    # With a remap set, the source answers +gid_for_codepoint+ for the
+    # *target* codepoints (0x11DB0 in the example) by translating them
+    # to the donor's *source* codepoints (0x41). Source codepoints not
+    # listed in the remap are hidden — only the remapped coverage is
+    # exposed. This matches the typical "use this donor for exactly
+    # these output characters" intent, and avoids leaking the donor's
+    # ASCII/PUA noise into the output.
     class Source
       MAX_COMPOUND_DEPTH = 32
 
-      attr_reader :font
+      attr_reader :font, :remap
 
-      def initialize(font)
+      # @param font [TrueTypeFont, OpenTypeFont, Ufo::Font] donor font
+      # @param remap [Hash{Integer=>Integer}, nil] optional
+      #   {source_codepoint => target_codepoint}. When present (even
+      #   empty), source codepoints not listed are hidden from
+      #   lookups. Pass +nil+ (the default) for the passthrough
+      #   behavior — every donor codepoint is exposed as-is.
+      def initialize(font, remap: nil)
         @font = font
         @bin_data_cache = nil
+
+        # Distinguish "no remap kwarg" (nil → passthrough) from
+        # "explicit empty remap" ({} → drop everything). The latter
+        # still flips the source into remapped mode, just with no
+        # entries — every donor codepoint gets filtered out.
+        return unless remap
+
+        @remap = remap.to_h.transform_keys(&:to_i).transform_values(&:to_i)
+        @inverse_remap = @remap.each_with_object({}) do |(src, target), h|
+          h[target] = src
+        end
       end
 
       # @return [Symbol] :ufo, :ttf, :otf
@@ -57,12 +92,21 @@ module Fontisan
       end
 
       # Find the gid for a Unicode codepoint in this source.
+      #
+      # When +remap+ was set at construction, +codepoint+ is treated as
+      # a *target* codepoint — the source codepoint that maps to it via
+      # +remap+ is what actually gets looked up. Returns +nil+ for
+      # codepoints the remap does not cover.
+      #
       # @param codepoint [Integer]
       # @return [Integer, nil]
       def gid_for_codepoint(codepoint)
+        src_cp = source_codepoint_for(codepoint)
+        return nil unless src_cp
+
         case @font
-        when Fontisan::Ufo::Font then ufo_gid_for(codepoint)
-        else bin_data_gid_for(codepoint)
+        when Fontisan::Ufo::Font then ufo_gid_for(src_cp)
+        else bin_data_gid_for(src_cp)
         end
       end
 
@@ -317,14 +361,51 @@ module Fontisan
       end
 
       # Add Unicode codepoints from the cmap that map to this gid.
+      #
+      # When +remap+ was set at construction, the source's raw codepoints
+      # are translated through the remap (source→target), and source
+      # codepoints not in the remap are dropped. Otherwise the raw cmap
+      # codepoints are attached as-is.
       def add_cmap_unicodes(gid, glyph)
-        cmap = @font.table("cmap")
-        return unless cmap
+        effective_codepoints_for_gid(gid).each { |cp| glyph.add_unicode(cp) }
+      end
+
+      # Translate a caller-facing codepoint to the donor's own codepoint.
+      # Without remap, the two are identical. With remap, the caller's
+      # codepoint is the *target*; look up the source codepoint that
+      # maps to it. Returns +nil+ if no remap entry covers the target.
+      def source_codepoint_for(codepoint)
+        return codepoint unless @remap
 
-        (cmap.unicode_mappings || {}).each do |cp, g|
-          glyph.add_unicode(cp) if g == gid
+        @inverse_remap[codepoint]
+      end
+
+      # Codepoints that should be attached to a glyph at the given gid,
+      # after applying the remap (if any).
+      def effective_codepoints_for_gid(gid)
+        raw_cmap = self.raw_cmap
+        raw_cmap.each_with_object([]) do |(src_cp, g), cps|
+          next unless g == gid
+
+          if @remap
+            target = @remap[src_cp]
+            cps << target if target
+          else
+            cps << src_cp
+          end
         end
       end
+
+      # The raw cmap hash from the donor's table. Always {src_cp => gid};
+      # never remapped. UFO sources return {} (no cmap table).
+      def raw_cmap
+        cmap = @font.table("cmap")
+        return {} unless cmap
+
+        cmap.unicode_mappings || {}
+      rescue StandardError
+        {}
+      end
     end
   end
 end

data/lib/fontisan/stitcher.rb

@@ -32,6 +32,7 @@ module Fontisan
     autoload :GlyphLimit,       "fontisan/stitcher/glyph_limit"
     autoload :CollectionResult, "fontisan/stitcher/collection_result"
     autoload :SubfontStats,     "fontisan/stitcher/collection_result"
+    autoload :FormatMetadata,   "fontisan/stitcher/format_metadata"
     autoload :PartitionStrategy, "fontisan/stitcher/partition_strategy"
 
     # Internal: pairs a compiled loaded font with its stats so
@@ -51,8 +52,8 @@ module Fontisan
       @deduplicate = deduplicate
     end
 
-    def add_source(label, font)
-      @sources[label.to_sym] = Source.new(font)
+    def add_source(label, font, remap: nil)
+      @sources[label.to_sym] = Source.new(font, remap: remap)
     end
 
     def include_range(range, from:, into:)
@@ -94,8 +95,8 @@ module Fontisan
       target = build_target_for(subfont)
       GlyphLimit.check!(target.glyphs.size, format: format)
 
-      compiler = compiler_for(format)
-      compiler.new(target).compile(output_path: path)
+      metadata = FormatMetadata.resolve(format)
+      metadata.compiler_class.new(target).compile(output_path: path)
 
       propagate_cbdt_tables(path) if cbdt_source
       path
@@ -109,7 +110,7 @@ module Fontisan
       end
       fonts = compiled.map(&:font)
 
-      collection_format = collection_format_for(format)
+      collection_format = FormatMetadata.resolve(format).collection_format
       Collection::Builder.new(fonts, format: collection_format,
                                      optimize: true).build_to_file(path)
 
@@ -138,20 +139,6 @@ module Fontisan
       cbdts.first
     end
 
-    def compiler_for(format)
-      case format.to_sym
-      when :ttf then Ufo::Compile::TtfCompiler
-      when :otf then Ufo::Compile::OtfCompiler
-      when :otf2 then Ufo::Compile::Otf2Compiler
-      else
-        raise ArgumentError, "unknown format: #{format.inspect}"
-      end
-    end
-
-    def collection_format_for(subfont_format)
-      subfont_format == :ttf ? :ttc : :otc
-    end
-
     def build_target_for(subfont_name)
       bindings = @subfonts[subfont_name] || []
       target = Ufo::Font.new
@@ -161,19 +148,14 @@ module Fontisan
       target
     end
 
-    def compile_subfont_to_loaded_font(subfont_name, format:)
-      compile_subfont_with_stats(subfont_name, format: format).font
-    end
-
     def compile_subfont_with_stats(subfont_name, format:)
       target = build_target_for(subfont_name)
       GlyphLimit.check!(target.glyphs.size, format: format)
 
-      ext = format == :ttf ? ".ttf" : ".otf"
+      metadata = FormatMetadata.resolve(format)
       Dir.mktmpdir do |dir|
-        sub_path = File.join(dir, "sub#{subfont_name}#{ext}")
-        compiler = compiler_for(format)
-        compiler.new(target).compile(output_path: sub_path)
+        sub_path = File.join(dir, "sub#{subfont_name}#{metadata.extension}")
+        metadata.compiler_class.new(target).compile(output_path: sub_path)
         propagate_cbdt_tables(sub_path) if cbdt_source
 
         loaded = Fontisan::FontLoader.load(sub_path)

data/lib/fontisan/svg/font_generator.rb

@@ -28,7 +28,7 @@ module Fontisan
       # @return [TrueTypeFont, OpenTypeFont] Font instance
       attr_reader :font
 
-      # @return [Hash] Glyph data map (glyph_id => {outline, unicode, name, advance})
+      # @return [Hash] Glyph data map (glyph_id => {outline, codepoints, name, advance})
       attr_reader :glyph_data
 
       # @return [Hash] Generation options
@@ -179,7 +179,7 @@ module Fontisan
 
           glyph_generator.generate_glyph_xml(
             data[:outline],
-            unicode: data[:unicode],
+            codepoints: data[:codepoints],
             glyph_name: data[:name],
             advance_width: data[:advance],
             indent: "      ",

data/lib/fontisan/svg/glyph_generator.rb

@@ -20,7 +20,7 @@ module Fontisan
     #
     # @example Generate SVG glyph element
     #   generator = GlyphGenerator.new(calculator)
-    #   xml = generator.generate_glyph_xml(outline, unicode: "A", advance_width: 600)
+    #   xml = generator.generate_glyph_xml(outline, codepoints: [0x41], advance_width: 600)
     class GlyphGenerator
       # @return [ViewBoxCalculator] Coordinate calculator
       attr_reader :calculator
@@ -38,23 +38,30 @@ module Fontisan
       # Generate SVG glyph element
       #
       # @param outline [Models::GlyphOutline] Glyph outline
-      # @param unicode [String, nil] Unicode character
-      # @param glyph_name [String, nil] Glyph name
+      # @param codepoints [Array<Integer>] Unicode codepoints that cmap
+      #   maps to this glyph. Empty for unmapped glyphs (.notdef, raw
+      #   ligatures, etc.). Each codepoint is rendered per SVG Fonts
+      #   spec: printable ASCII as the character (XML-escaped), others
+      #   as &#xHEX; entities. Multiple codepoints are concatenated —
+      #   rare but valid (e.g. a glyph mapped from both space and
+      #   non-breaking space).
+      # @param glyph_name [String, nil] Glyph name from the post table
       # @param advance_width [Integer] Horizontal advance width
       # @param indent [String] Indentation string
       # @return [String] XML glyph element
-      def generate_glyph_xml(outline, unicode: nil, glyph_name: nil,
+      def generate_glyph_xml(outline, codepoints: [], glyph_name: nil,
 advance_width: 0, indent: "      ")
-        # Build attribute parts
         attr_parts = []
 
-        attr_parts << "unicode=\"#{escape_xml(unicode)}\"" if unicode
-        attr_parts << "glyph-name=\"#{escape_xml(glyph_name)}\"" if glyph_name
-        attr_parts << "horiz-adv-x=\"#{advance_width}\"" if advance_width&.positive?
+        unless codepoints.empty?
+          attr_parts << %(unicode="#{format_codepoints(codepoints)}")
+        end
+        attr_parts << %(glyph-name="#{escape_xml(glyph_name)}") if glyph_name
+        attr_parts << %(horiz-adv-x="#{advance_width}") if advance_width&.positive?
 
         # Generate SVG path with Y-axis transformation
         path_data = generate_svg_path(outline)
-        attr_parts << "d=\"#{path_data}\"" if path_data && !path_data.empty?
+        attr_parts << %(d="#{path_data}") if path_data && !path_data.empty?
 
         "#{indent}<glyph #{attr_parts.join(' ')}/>"
       end
@@ -88,6 +95,34 @@ advance_width: 0, indent: "      ")
 
       private
 
+      # Format an array of codepoints as the SVG `unicode=` attribute
+      # value. Returns the FINAL string — already escaped / entity-fied.
+      # The caller must not re-escape it (would double-escape the
+      # entities this method emits).
+      #
+      # Per SVG Fonts spec, each codepoint renders as either:
+      #   - printable ASCII (0x20..0x7E): the character itself, with
+      #     XML-special chars (&, <, >, ", ') escaped
+      #   - any other codepoint: a numeric entity &#xHEX;
+      #
+      # Multiple codepoints are concatenated in codepoint order. The
+      # SVG spec accepts this for ligature-style mappings.
+      def format_codepoints(codepoints)
+        codepoints.map { |cp| format_codepoint(cp) }.join
+      end
+
+      def format_codepoint(cp)
+        if printable_ascii?(cp)
+          escape_xml(cp.chr(Encoding::UTF_8))
+        else
+          "&#x#{cp.to_s(16).upcase};"
+        end
+      end
+
+      def printable_ascii?(cp)
+        (0x20..0x7E).cover?(cp)
+      end
+
       # Build SVG path for a contour with Y-axis transformation
       #
       # @param contour [Array<Hash>] Array of point hashes

data/lib/fontisan/unicode/plane.rb

@@ -15,18 +15,6 @@ module Fontisan
       TIP = 3
       SSP = 14
 
-      # The handful of mega-blocks large enough to overflow a single
-      # plane's 65,535-glyph cap when partitioning by plane. Range +
-      # label only — full Unicode Blocks.txt data lives in +Block+
-      # (follow-up).
-      LARGE_CJK_BLOCKS = {
-        "CJK_Ext_B" => 0x2A700..0x2B73F,
-        "CJK_Ext_C" => 0x2B740..0x2B81F,
-        "CJK_Ext_D" => 0x2B820..0x2CEAF,
-        "CJK_Ext_E" => 0x2CEB0..0x2EBEF,
-        "CJK_Ext_F" => 0x2EBF0..0x2EE5F,
-      }.freeze
-
       # @param codepoint [Integer]
       # @return [Integer] plane number (0..16)
       def self.of(codepoint)

data/lib/fontisan/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fontisan
-  VERSION = "0.4.9"
+  VERSION = "0.4.10"
 end

data/lib/fontisan.rb

@@ -32,6 +32,7 @@ require "logger"
 require "bindata"
 require "zlib"
 require "stringio"
+require "tmpdir"
 require "lutaml/model"
 
 # Configure lutaml-model to use Nokogiri adapter for XML serialization

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fontisan
 version: !ruby/object:Gem::Version
-  version: 0.4.9
+  version: 0.4.10
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-03 00:00:00.000000000 Z
+date: 2026-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -434,6 +434,7 @@ files:
 - lib/fontisan/stitcher.rb
 - lib/fontisan/stitcher/collection_result.rb
 - lib/fontisan/stitcher/deduplicator.rb
+- lib/fontisan/stitcher/format_metadata.rb
 - lib/fontisan/stitcher/glyph_limit.rb
 - lib/fontisan/stitcher/glyph_signature.rb
 - lib/fontisan/stitcher/partition_strategy.rb