fontisan 0.4.7 → 0.4.8

data/lib/fontisan/commands/validate_collection_command.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Commands
+    # Validates the structural integrity of a TTC/OTC/dfont collection
+    # (TODO 74). Complements {ValidateCommand}, which runs profile-based
+    # checks against a single face. This command runs collection-level
+    # checks: face count, per-face glyph cap, optional cmap-union size.
+    #
+    # Returns an integer exit code (0 = all checks passed, 1 = any check
+    # failed) suitable for use as the CLI's exit status.
+    #
+    # The command is intentionally narrow: it does not subclass
+    # {BaseCommand} (which eagerly loads a single font at construction
+    # time) because the input here is a collection, not a single face.
+    # It owns its own loading via {Collection::Reader}.
+    class ValidateCollectionCommand
+      # Per-check result. The +message+ is +nil+ on pass.
+      #
+      # @!attribute [r] name
+      #   @return [Symbol] check identifier (:face_count, :glyph_cap, :cmap_union)
+      # @!attribute [r] passed
+      #   @return [Boolean]
+      # @!attribute [r] message
+      #   @return [String, nil] human-readable failure detail
+      Check = Struct.new(:name, :passed, :message, keyword_init: true) do
+        # Predicate form so callers can write +check.passed?+ instead of
+        # +check.passed+. Struct does not provide the +?+ suffix
+        # automatically.
+        def passed?
+          passed
+        end
+      end
+
+      DEFAULT_MAX_GLYPHS = 65_535
+
+      # @param input [String] path to a TTC/OTC/dfont
+      # @param expected_faces [Integer, nil] required face count, or nil to skip
+      # @param max_glyphs [Integer] per-face glyph cap (default 65,535)
+      # @param expected_cmap_union [Integer, nil] minimum cmap-union size, or nil to skip
+      def initialize(input:, expected_faces: nil, max_glyphs: DEFAULT_MAX_GLYPHS,
+                     expected_cmap_union: nil)
+        @input = input
+        @expected_faces = expected_faces
+        @max_glyphs = max_glyphs
+        @expected_cmap_union = expected_cmap_union
+      end
+
+      # @return [Integer] 0 if all checks passed, 1 otherwise
+      def run
+        reader = Collection::Reader.open(@input)
+        @checks = [
+          check_face_count(reader),
+          check_glyph_cap(reader),
+          check_cmap_union(reader),
+        ].compact
+
+        render_report(reader)
+        @checks.all?(&:passed?) ? 0 : 1
+      end
+
+      # @return [Array<Check>] the most recent run's checks
+      attr_reader :checks
+
+      private
+
+      def check_face_count(reader)
+        return nil unless @expected_faces
+
+        actual = reader.face_count
+        passed = actual == @expected_faces
+        Check.new(
+          name: :face_count,
+          passed: passed,
+          message: passed ? nil : "expected #{@expected_faces} faces, got #{actual}",
+        )
+      end
+
+      def check_glyph_cap(reader)
+        over = reader.stats.select { |s| s.glyph_count > @max_glyphs }
+        Check.new(
+          name: :glyph_cap,
+          passed: over.empty?,
+          message: over.empty? ? nil : "faces over cap: #{over.map { |s| "##{s.index}=#{s.glyph_count}" }.join(', ')}",
+        )
+      end
+
+      def check_cmap_union(reader)
+        return nil unless @expected_cmap_union
+
+        actual = reader.cmap_union.size
+        passed = actual >= @expected_cmap_union
+        Check.new(
+          name: :cmap_union,
+          passed: passed,
+          message: passed ? nil : "cmap union #{actual} < expected #{@expected_cmap_union}",
+        )
+      end
+
+      # Default rendering. Callers wanting structured output can
+      # instantiate the command, call +#run+, then read +#checks+
+      # directly instead of relying on stdout.
+      def render_report(reader)
+        reader.stats.each do |s|
+          marker = s.glyph_count <= @max_glyphs ? "✓" : "✗"
+          puts format("face %<index>d: %<glyphs>7d glyphs %<marker>s",
+                      index: s.index, glyphs: s.glyph_count, marker: marker)
+        end
+        puts "all #{reader.face_count} faces within #{@max_glyphs}-glyph cap ✓"
+
+        @checks.each do |check|
+          if check.passed?
+            puts "#{check.name}: ✓"
+          else
+            puts "#{check.name}: ✗ (#{check.message})"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/commands.rb

@@ -13,6 +13,7 @@ module Fontisan
     autoload :InfoCommand, "fontisan/commands/info_command"
     autoload :InstanceCommand, "fontisan/commands/instance_command"
     autoload :LsCommand, "fontisan/commands/ls_command"
+    autoload :MultiFormatOutput, "fontisan/commands/multi_format_output"
     autoload :OpticalSizeCommand, "fontisan/commands/optical_size_command"
     autoload :PackCommand, "fontisan/commands/pack_command"
     autoload :ScriptsCommand, "fontisan/commands/scripts_command"
@@ -20,6 +21,7 @@ module Fontisan
     autoload :TablesCommand, "fontisan/commands/tables_command"
     autoload :UnicodeCommand, "fontisan/commands/unicode_command"
     autoload :UnpackCommand, "fontisan/commands/unpack_command"
+    autoload :ValidateCollectionCommand, "fontisan/commands/validate_collection_command"
     autoload :ValidateCommand, "fontisan/commands/validate_command"
     autoload :VariableCommand, "fontisan/commands/variable_command"
   end

data/lib/fontisan/error.rb

@@ -237,6 +237,31 @@ module Fontisan
     end
   end
 
+  # Partition strategy could not satisfy the requested cap.
+  #
+  # Raised by {Stitcher::PartitionStrategy} when a single Unicode block
+  # contains more codepoints than the configured cap, so the partitioner
+  # cannot sub-split it further. This is a partitioning-time detection
+  # distinct from {GlyphLimitExceededError}, which fires at compile time
+  # after the Stitcher has produced more glyphs than the output format
+  # supports. Both surface the same underlying constraint (65,535-glyph
+  # cap) but at different stages.
+  class PartitionCapExceededError < Error
+    attr_reader :block_label, :actual, :cap
+
+    # @param block_label [String] e.g. "CJK_Ext_B", or "plane_N" if the
+    #   overflow is not attributable to a known block
+    # @param actual [Integer] number of codepoints in the block
+    # @param cap [Integer] the cap that was exceeded
+    def initialize(block_label:, actual:, cap:)
+      @block_label = block_label
+      @actual = actual
+      @cap = cap
+      super("single Unicode block #{block_label} (#{actual} cps) exceeds " \
+            "cap #{cap}; cannot sub-split further")
+    end
+  end
+
   # Variation data corrupted (for use in data_extractor)
   #
   # Raised when extracted variation data appears corrupted.

data/lib/fontisan/models.rb

@@ -15,7 +15,6 @@ module Fontisan
     autoload :CollectionListInfo, "fontisan/models/collection_list_info"
     autoload :CollectionValidationReport,
              "fontisan/models/collection_validation_report"
-    autoload :Cldr, "fontisan/models/cldr"
     autoload :ColorGlyph, "fontisan/models/color_glyph"
     autoload :ColorLayer, "fontisan/models/color_layer"
     autoload :ColorPalette, "fontisan/models/color_palette"

data/lib/fontisan/stitcher/collection_result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    # Per-subfont stats computed from the loaded, on-disk subfont (not the
+    # in-memory UFO target — the compiler may add glyphs, e.g. .notdef).
+    SubfontStats = Struct.new(:name, :glyph_count, :codepoint_count,
+                              keyword_init: true)
+
+    # Return value of {Stitcher#write_collection}. Carries the output path,
+    # total bytes, and one {SubfontStats} per declared subfont.
+    CollectionResult = Struct.new(:path, :bytes, :subfonts, keyword_init: true) do
+      def face_count
+        subfonts.size
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    module PartitionStrategy
+      # 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
+
+        # @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)
+          raise NotImplementedError,
+                "#{self.class} must implement #call"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    module PartitionStrategy
+      # The result of partitioning a codepoint set: an ordered list of
+      # {Partition}s. Applying a blueprint to a Stitcher declares one
+      # subfont per partition.
+      Blueprint = Struct.new(:partitions, keyword_init: true) do
+        # @param stitcher [Fontisan::Stitcher]
+        # @return [Array<Symbol>] names of subfonts declared
+        def apply_to(stitcher)
+          partitions.each { |p| p.apply_to(stitcher) }
+          partitions.map(&:name)
+        end
+
+        # @return [Array<Symbol>]
+        def names
+          partitions.map(&:name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    module PartitionStrategy
+      # Partition codepoints by Unicode plane (BMP, SMP, SIP, …).
+      #
+      # 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.
+      #
+      # If a single CJK extension block alone exceeds +cap+, raises
+      # {Fontisan::GlyphLimitExceededError} — 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.
+      class ByPlane < Base
+        # @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_plane(cp_map)
+          partitions = grouped.flat_map do |plane_num, entries|
+            build_partitions_for_plane(plane_num, entries, cap)
+          end
+          Blueprint.new(partitions: partitions)
+        end
+
+        private
+
+        def group_by_plane(cp_map)
+          cp_map.group_by { |cp, _label| Fontisan::Unicode::Plane.of(cp) }
+        end
+
+        def build_partitions_for_plane(plane_num, entries, cap)
+          if entries.size <= cap
+            return [single_partition(plane_num, entries)]
+          end
+
+          sub_split_by_block(plane_num, entries, cap)
+        end
+
+        def single_partition(plane_num, entries)
+          Partition.new(
+            name: :"plane_#{plane_num}",
+            cps: entries.map(&:first),
+            donor_map: entries.to_h,
+          )
+        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.
+        def sub_split_by_block(plane_num, entries, cap)
+          buckets = bucket_by_large_block(entries)
+          partitions = []
+          suffix = "a"
+
+          buckets.each do |label, bucket_entries|
+            if large_block?(label) && bucket_entries.size > cap
+              raise PartitionCapExceededError.new(
+                block_label: label,
+                actual: bucket_entries.size,
+                cap: cap,
+              )
+            end
+
+            chunks(bucket_entries, cap).each do |chunk|
+              partitions << Partition.new(
+                name: :"plane_#{plane_num}_#{suffix}",
+                cps: chunk.map(&:first),
+                donor_map: chunk.to_h,
+              )
+              suffix = suffix.succ
+            end
+          end
+          partitions
+        end
+
+        def large_block?(label)
+          Fontisan::Unicode::Plane::LARGE_CJK_BLOCKS.key?(label)
+        end
+
+        # Split +entries+ into sub-arrays of at most +cap+ each.
+        def chunks(entries, cap)
+          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)
+          buckets = { other: [] }
+          Fontisan::Unicode::Plane::LARGE_CJK_BLOCKS.each_key do |label|
+            buckets[label] = []
+          end
+
+          entries.each do |cp, label|
+            block = find_large_block(cp)
+            if block
+              buckets[block] << [cp, label]
+            else
+              buckets[:other] << [cp, label]
+            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|
+            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|
+            range.include?(codepoint)
+          end&.first
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    module PartitionStrategy
+      # One slice of a partitioned codepoint set. Each partition names
+      # a target subfont and the codepoints + donor mapping that should
+      # land in it.
+      #
+      # {#apply_to} pushes the partition's bindings into a Stitcher via
+      # +include_codepoints_map+ (TODO 68). If that API is unavailable
+      # (older Stitcher), it falls back to one +include_codepoints+
+      # call per donor — but the preferred path is the map API.
+      Partition = Struct.new(:name, :cps, :donor_map, keyword_init: true) do
+        # @param stitcher [Fontisan::Stitcher]
+        # @return [void]
+        def apply_to(stitcher)
+          slice = cps.to_h { |cp| [cp, donor_map[cp]] }
+          stitcher.include_codepoints_map(slice, into: name)
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/stitcher/partition_strategy.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    # Namespace for codepoint partitioners that split a codepoint set
+    # across named subfonts while respecting the format's glyph cap.
+    #
+    # A partitioner is a strategy object with a single entry point
+    # (`.partition`) that takes a +{codepoint => donor}+ map and returns
+    # a {Blueprint}. The blueprint is then applied to a Stitcher via
+    # {Blueprint#apply_to}.
+    #
+    # Adding a new partitioner = adding a new file + a new entry here.
+    # No edits to existing partitioners required (open/closed).
+    module PartitionStrategy
+      autoload :Base, "fontisan/stitcher/partition_strategy/base"
+      autoload :Blueprint, "fontisan/stitcher/partition_strategy/blueprint"
+      autoload :Partition, "fontisan/stitcher/partition_strategy/partition"
+      autoload :ByPlane, "fontisan/stitcher/partition_strategy/by_plane"
+    end
+  end
+end

data/lib/fontisan/stitcher.rb

@@ -25,11 +25,20 @@ module Fontisan
   #   stitcher.include_range(0x4E00..0x9FFF, from: :noto_cjk, into: :cjk)
   #   stitcher.write_collection("out.otc", format: :otf2)
   class Stitcher
-    autoload :Source,          "fontisan/stitcher/source"
-    autoload :Selector,        "fontisan/stitcher/selector"
-    autoload :GlyphSignature,  "fontisan/stitcher/glyph_signature"
-    autoload :Deduplicator,    "fontisan/stitcher/deduplicator"
-    autoload :GlyphLimit,      "fontisan/stitcher/glyph_limit"
+    autoload :Source,           "fontisan/stitcher/source"
+    autoload :Selector,         "fontisan/stitcher/selector"
+    autoload :GlyphSignature,   "fontisan/stitcher/glyph_signature"
+    autoload :Deduplicator,     "fontisan/stitcher/deduplicator"
+    autoload :GlyphLimit,       "fontisan/stitcher/glyph_limit"
+    autoload :CollectionResult, "fontisan/stitcher/collection_result"
+    autoload :SubfontStats,     "fontisan/stitcher/collection_result"
+    autoload :PartitionStrategy, "fontisan/stitcher/partition_strategy"
+
+    # Internal: pairs a compiled loaded font with its stats so
+    # +write_collection+ can build the collection and the result from a
+    # single compilation pass.
+    CompiledSubfont = Struct.new(:name, :font, :stats, keyword_init: true)
+    private_constant :CompiledSubfont
 
     DEFAULT_DEDUPLICATE = true
 
@@ -54,6 +63,13 @@ module Fontisan
       Selector::Codepoints.new(codepoints).apply(source(from), @subfonts[into])
     end
 
+    def include_codepoints_map(cp_map, into:)
+      cp_map.to_h
+        .group_by { |_cp, label| label }
+        .transform_values { |pairs| pairs.map(&:first).sort }
+        .each { |label, cps| include_codepoints(cps, from: label, into: into) }
+    end
+
     def include_gid(donor_gid, from:, into:)
       Selector::Gid.new(donor_gid).apply(source(from), @subfonts[into])
     end
@@ -89,13 +105,19 @@ module Fontisan
       raise ArgumentError, "no subfonts declared" if @subfonts.empty?
 
       compiled = @subfonts.keys.map do |name|
-        compile_subfont_to_loaded_font(name, format: format)
+        compile_subfont_with_stats(name, format: format)
       end
+      fonts = compiled.map(&:font)
 
       collection_format = collection_format_for(format)
-      Collection::Builder.new(compiled, format: collection_format,
-                                        optimize: true).build_to_file(path)
-      path
+      Collection::Builder.new(fonts, format: collection_format,
+                                     optimize: true).build_to_file(path)
+
+      CollectionResult.new(
+        path: path,
+        bytes: File.size(path),
+        subfonts: compiled.map(&:stats),
+      )
     end
 
     private
@@ -140,6 +162,10 @@ module Fontisan
     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)
 
@@ -148,7 +174,15 @@ module Fontisan
         sub_path = File.join(dir, "sub#{subfont_name}#{ext}")
         compiler = compiler_for(format)
         compiler.new(target).compile(output_path: sub_path)
-        return Fontisan::FontLoader.load(sub_path)
+        propagate_cbdt_tables(sub_path) if cbdt_source
+
+        loaded = Fontisan::FontLoader.load(sub_path)
+        stats = SubfontStats.new(
+          name: subfont_name,
+          glyph_count: loaded.table("maxp")&.num_glyphs || 0,
+          codepoint_count: (loaded.table("cmap")&.unicode_mappings || {}).size,
+        )
+        CompiledSubfont.new(name: subfont_name, font: loaded, stats: stats)
       end
     end
 

data/lib/fontisan/ufo/compile/name.rb

@@ -31,7 +31,7 @@ module Fontisan
           family = font.info.family_name || "Untitled"
           subfamily = font.info.style_name || "Regular"
           ps_name = font.info.postscript_font_name || "#{family}-#{subfamily}"
-          full_name = "#{family} #{subfamily}".strip
+          full_name = font.info.postscript_full_name || "#{family} #{subfamily}".strip
           major = font.info.version_major || 0
           minor = font.info.version_minor || 0
           version_str = "Version #{major}.#{minor}"
@@ -72,7 +72,7 @@ module Fontisan
 
           header + body + storage
         end
-        private_class_method :format0_bytes, :default_records
+        private_class_method :format0_bytes
       end
     end
   end

data/lib/fontisan/ufo/info.rb

@@ -41,6 +41,54 @@ module Fontisan
         end
       end
 
+      # Build a +Ufo::Info+ for one subfont of a collection. The family
+      # name embeds the subfont name (e.g. +"MyFont CJK"+), and the
+      # PostScript name uses the hyphenated form (e.g. +"MyFont-CJK"+).
+      #
+      # +version+ is parsed into +version_major+ / +version_minor+ per
+      # the UFO major.minor shape (patch is dropped).
+      #
+      # +trademark+ is stored under +extras["openTypeNameTrademark"]+
+      # because it is not in +STANDARD_FIELDS+ yet — see TODO 71
+      # out-of-scope follow-up.
+      #
+      # @param family [String] collection-wide family name
+      # @param subfont [String, Symbol] subfont identifier (appended to family)
+      # @param version [String, Integer] e.g. "0.1", "1", "1.2.3"
+      # @param subfamily [String] OpenType subfamily (default "Regular")
+      # @param copyright [String, nil]
+      # @param trademark [String, nil]
+      # @return [Info]
+      def self.for_subfont(family:, subfont:, version:,
+                           subfamily: "Regular",
+                           copyright: nil, trademark: nil)
+        major, minor = parse_version(version)
+        subfont_str = subfont.to_s
+        values = {
+          family_name: "#{family} #{subfont_str}",
+          style_name: subfamily,
+          version_major: major,
+          version_minor: minor,
+          postscript_font_name: "#{family}-#{subfont_str}",
+          postscript_full_name: "#{family} #{subfont_str}",
+        }
+        values[:copyright] = copyright if copyright
+        values["openTypeNameTrademark"] = trademark if trademark
+        new(values)
+      end
+
+      # @param version [String, Integer]
+      # @return [Array(Integer, Integer)] [major, minor]
+      def self.parse_version(version)
+        case version.to_s
+        when /\A(\d+)\.(\d+)\.\d+\z/ then [Regexp.last_match(1).to_i, Regexp.last_match(2).to_i]
+        when /\A(\d+)\.(\d+)\z/      then [Regexp.last_match(1).to_i, Regexp.last_match(2).to_i]
+        when /\A(\d+)\z/             then [Regexp.last_match(1).to_i, 0]
+        else [0, 0]
+        end
+      end
+      private_class_method :parse_version
+
       # @return [Hash] a Hash<String, Object> suitable for emit() to
       #   serialize back to plist. Keys are in camelCase per UFO 3.
       def to_plist

data/lib/fontisan/unicode/plane.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Unicode
+    # Unicode plane metadata. A plane is a contiguous range of 65,536
+    # codepoints; +cp >> 16+ is the plane number.
+    #
+    # Plane labels follow the Unicode standard names. Unassigned planes
+    # fall back to +"Plane_N"+. This is a pure-data module — no I/O, no
+    # state, no dependency on tables or stitcher.
+    module Plane
+      BMP = 0
+      SMP = 1
+      SIP = 2
+      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)
+        codepoint >> 16
+      end
+
+      # @param plane [Integer]
+      # @return [String] human-readable plane label
+      def self.label(plane)
+        case plane
+        when BMP then "BMP"
+        when SMP then "SMP"
+        when SIP then "SIP"
+        when TIP then "TIP"
+        when SSP then "SSP"
+        else "Plane_#{plane}"
+        end
+      end
+
+      # @param codepoint [Integer]
+      # @return [String] label of the plane containing +codepoint+
+      def self.label_of(codepoint)
+        label(of(codepoint))
+      end
+    end
+  end
+end

data/lib/fontisan/unicode.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Namespace hub for Unicode metadata used by font tooling.
+#
+# Plane/Block/Script metadata is a separate concern from font format
+# parsing — it is pure Unicode knowledge. Keeping it under its own
+# namespace (rather than scattering it across +Tables+ or +Stitcher+)
+# keeps the data MECE: one concept, one home.
+#
+# Each metadata concept (Plane, Block, Script) lives in its own file so
+# that adding a new concept is additive (open/closed).
+
+module Fontisan
+  module Unicode
+    autoload :Plane, "fontisan/unicode/plane"
+  end
+end

data/lib/fontisan/version.rb

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