fontisan 0.2.0 → 0.2.1

data/lib/fontisan/hints/postscript_hint_extractor.rb

@@ -29,6 +29,28 @@ module Fontisan
       HSTEM3 = 12 << 8 | 2
       VSTEM3 = 12 << 8 | 1
 
+      # Extract complete hint data from OpenType/CFF font
+      #
+      # This extracts both font-level hints (CFF Private dict) and
+      # per-glyph hints from CharStrings.
+      #
+      # @param font [OpenTypeFont] OpenType font with CFF table
+      # @return [Models::HintSet] Complete hint set
+      def extract_from_font(font)
+        hint_set = Models::HintSet.new(format: "postscript")
+
+        # Extract font-level Private dict hints
+        hint_set.private_dict_hints = extract_private_dict_hints(font).to_json
+
+        # Extract per-glyph CharString hints
+        extract_charstring_hints(font, hint_set)
+
+        # Update metadata
+        hint_set.has_hints = !hint_set.empty?
+
+        hint_set
+      end
+
       # Extract hints from CFF CharString
       #
       # @param charstring [CharString, String] CFF CharString object or bytes
@@ -249,6 +271,84 @@ module Fontisan
           source_format: :postscript
         )
       end
+
+      # Extract Private dict hints from CFF table
+      #
+      # Private dict contains font-level hint parameters like BlueValues,
+      # StdHW, StdVW, etc.
+      #
+      # @param font [OpenTypeFont] OpenType font
+      # @return [Hash] Private dict hint parameters
+      def extract_private_dict_hints(font)
+        hints = {}
+
+        return hints unless font.has_table?("CFF ")
+
+        cff_table = font.table("CFF ")
+        return hints unless cff_table
+
+        # Get Private DICT for first font (index 0)
+        private_dict = cff_table.private_dict(0)
+        return hints unless private_dict
+
+        # Extract hint-related parameters from Private DICT
+        # These are the key hinting parameters in CFF
+        hints[:blue_values] = private_dict.blue_values if private_dict.respond_to?(:blue_values)
+        hints[:other_blues] = private_dict.other_blues if private_dict.respond_to?(:other_blues)
+        hints[:family_blues] = private_dict.family_blues if private_dict.respond_to?(:family_blues)
+        hints[:family_other_blues] = private_dict.family_other_blues if private_dict.respond_to?(:family_other_blues)
+        hints[:blue_scale] = private_dict.blue_scale if private_dict.respond_to?(:blue_scale)
+        hints[:blue_shift] = private_dict.blue_shift if private_dict.respond_to?(:blue_shift)
+        hints[:blue_fuzz] = private_dict.blue_fuzz if private_dict.respond_to?(:blue_fuzz)
+        hints[:std_hw] = private_dict.std_hw if private_dict.respond_to?(:std_hw)
+        hints[:std_vw] = private_dict.std_vw if private_dict.respond_to?(:std_vw)
+        hints[:stem_snap_h] = private_dict.stem_snap_h if private_dict.respond_to?(:stem_snap_h)
+        hints[:stem_snap_v] = private_dict.stem_snap_v if private_dict.respond_to?(:stem_snap_v)
+        hints[:force_bold] = private_dict.force_bold if private_dict.respond_to?(:force_bold)
+        hints[:language_group] = private_dict.language_group if private_dict.respond_to?(:language_group)
+
+        hints.compact
+      rescue StandardError => e
+        warn "Failed to extract Private dict hints: #{e.message}"
+        {}
+      end
+
+      # Extract per-glyph CharString hints from CFF table
+      #
+      # @param font [OpenTypeFont] OpenType font
+      # @param hint_set [Models::HintSet] Hint set to populate
+      # @return [void]
+      def extract_charstring_hints(font, hint_set)
+        return unless font.has_table?("CFF ")
+
+        cff_table = font.table("CFF ")
+        return unless cff_table
+
+        # Get CharStrings INDEX
+        charstrings_index = cff_table.charstrings_index(0)
+        return unless charstrings_index
+
+        # Iterate through all glyphs
+        glyph_count = cff_table.glyph_count(0)
+        (0...glyph_count).each do |glyph_id|
+          begin
+            # Get CharString for this glyph
+            charstring = cff_table.charstring_for_glyph(glyph_id, 0)
+            next unless charstring
+
+            # Extract hints from CharString
+            hints = extract(charstring)
+            next if hints.empty?
+
+            # Store glyph hints
+            hint_set.add_glyph_hints(glyph_id, hints)
+          rescue StandardError => e
+            warn "Failed to extract hints for glyph #{glyph_id}: #{e.message}"
+          end
+        end
+      rescue StandardError => e
+        warn "Failed to extract CharString hints: #{e.message}"
+      end
     end
   end
 end

data/lib/fontisan/hints/truetype_hint_applier.rb

@@ -1,70 +1,116 @@
 # frozen_string_literal: true
 
-require_relative "../models/hint"
-
 module Fontisan
   module Hints
-    # Applies rendering hints to TrueType glyph data
+    # Applies rendering hints to TrueType font tables
+    #
+    # This applier writes TrueType hint data into font-level tables:
+    # - fpgm (Font Program) - bytecode executed once at font initialization
+    # - prep (Control Value Program) - bytecode for glyph preparation
+    # - cvt (Control Values) - array of 16-bit values for hinting metrics
     #
-    # This applier converts universal Hint objects into TrueType bytecode
-    # instructions and integrates them into glyph data. It ensures proper
-    # instruction sequencing and maintains compatibility with TrueType
-    # instruction execution model.
+    # The applier ensures proper table structure with correct checksums
+    # and does not corrupt the font if hint application fails.
     #
-    # @example Apply hints to a glyph
+    # @example Apply hints from a HintSet
     #   applier = TrueTypeHintApplier.new
-    #   glyph_with_hints = applier.apply(glyph, hints)
+    #   tables = {}
+    #   updated_tables = applier.apply(hint_set, tables)
     class TrueTypeHintApplier
-      # Apply hints to TrueType glyph
+      # Apply TrueType hints to font tables
       #
-      # @param glyph [Glyph] Target glyph
-      # @param hints [Array<Hint>] Hints to apply
-      # @return [Glyph] Glyph with applied hints
-      def apply(glyph, hints)
-        return glyph if hints.nil? || hints.empty?
-        return glyph if glyph.nil?
+      # @param hint_set [HintSet] Hint data to apply
+      # @param tables [Hash] Font tables to update
+      # @return [Hash] Updated font tables
+      def apply(hint_set, tables)
+        return tables if hint_set.nil? || hint_set.empty?
+        return tables unless hint_set.format == "truetype"
 
-        # Convert hints to TrueType instructions
-        instructions = build_instructions(hints)
+        # Write fpgm table if present
+        if hint_set.font_program && !hint_set.font_program.empty?
+          tables["fpgm"] = build_fpgm_table(hint_set.font_program)
+        end
 
-        # Apply to glyph (this is a simplified version)
-        # In a real implementation, we would need to:
-        # 1. Analyze existing glyph structure
-        # 2. Insert instructions at appropriate points
-        # 3. Update glyph instruction data
+        # Write prep table if present
+        if hint_set.control_value_program && !hint_set.control_value_program.empty?
+          tables["prep"] = build_prep_table(hint_set.control_value_program)
+        end
 
-        # For now, we just return the glyph as-is since
-        # this is a complex operation requiring deep integration
-        # with the glyph structure
-        glyph
+        # Write cvt table if present
+        if hint_set.control_values && !hint_set.control_values.empty?
+          tables["cvt "] = build_cvt_table(hint_set.control_values)
+        end
+
+        # Future enhancement: Apply per-glyph hints to glyf table
+        # For now, font-level tables only
+
+        tables
       end
 
       private
 
-      # Build TrueType instruction sequence from hints
+      # Build fpgm (Font Program) table
       #
-      # @param hints [Array<Hint>] Hints to convert
-      # @return [Array<Integer>] Instruction bytes
-      def build_instructions(hints)
-        instructions = []
+      # @param program_data [String] Raw bytecode
+      # @return [Hash] Table structure with tag, data, and checksum
+      def build_fpgm_table(program_data)
+        {
+          tag: "fpgm",
+          data: program_data,
+          checksum: calculate_checksum(program_data),
+        }
+      end
 
-        hints.each do |hint|
-          hint_instructions = hint.to_truetype
-          instructions.concat(hint_instructions) if hint_instructions
-        end
+      # Build prep (Control Value Program) table
+      #
+      # @param program_data [String] Raw bytecode
+      # @return [Hash] Table structure with tag, data, and checksum
+      def build_prep_table(program_data)
+        {
+          tag: "prep",
+          data: program_data,
+          checksum: calculate_checksum(program_data),
+        }
+      end
+
+      # Build cvt (Control Values) table
+      #
+      # CVT values are 16-bit signed integers (FWORD) in big-endian format.
+      # Each value represents a design-space coordinate used for hinting.
+      #
+      # @param control_values [Array<Integer>] Array of 16-bit signed values
+      # @return [Hash] Table structure with tag, data, and checksum
+      def build_cvt_table(control_values)
+        # Pack as 16-bit big-endian signed integers (s> = signed big-endian)
+        data = control_values.pack("s>*")
 
-        instructions
+        {
+          tag: "cvt ",
+          data: data,
+          checksum: calculate_checksum(data),
+        }
       end
 
-      # Validate instruction sequence
+      # Calculate OpenType table checksum
+      #
+      # OpenType spec requires tables to be checksummed as 32-bit unsigned
+      # integers in big-endian format. The table is padded to a multiple of
+      # 4 bytes with zeros before checksum calculation.
       #
-      # @param instructions [Array<Integer>] Instructions to validate
-      # @return [Boolean] True if valid
-      def valid_instructions?(instructions)
-        return true if instructions.empty?
+      # @param data [String] Table data
+      # @return [Integer] 32-bit checksum
+      def calculate_checksum(data)
+        # Pad to 4-byte boundary with zeros
+        padding_needed = (4 - data.length % 4) % 4
+        padded = data + ("\x00" * padding_needed)
+
+        # Sum as 32-bit unsigned integers in big-endian
+        checksum = 0
+        (0...padded.length).step(4) do |i|
+          checksum = (checksum + padded[i, 4].unpack1("N")) & 0xFFFFFFFF
+        end
 
-        # Basic validation - check for valid opcodes
-        instructions.all? { |byte| byte >= 0 && byte <= 255 }
+        checksum
       end
     end
   end

data/lib/fontisan/hints/truetype_hint_extractor.rb

@@ -35,6 +35,30 @@ module Fontisan
       DELTAP2 = 0x71
       DELTAP3 = 0x72
 
+      # Extract complete hint data from TrueType font
+      #
+      # This extracts both font-level hints (fpgm, prep, cvt tables) and
+      # per-glyph hints from glyph instructions.
+      #
+      # @param font [TrueTypeFont] TrueType font object
+      # @return [Models::HintSet] Complete hint set
+      def extract_from_font(font)
+        hint_set = Models::HintSet.new(format: "truetype")
+
+        # Extract font-level programs
+        hint_set.font_program = extract_font_program(font)
+        hint_set.control_value_program = extract_control_value_program(font)
+        hint_set.control_values = extract_control_values(font)
+
+        # Extract per-glyph hints
+        extract_glyph_hints(font, hint_set)
+
+        # Update metadata
+        hint_set.has_hints = !hint_set.empty?
+
+        hint_set
+      end
+
       # Extract hints from TrueType glyph
       #
       # @param glyph [Glyph] TrueType glyph with instructions
@@ -157,6 +181,109 @@ module Fontisan
           nil
         end
       end
+
+      # Extract font program (fpgm table)
+      #
+      # @param font [TrueTypeFont] TrueType font
+      # @return [String] Font program bytecode (binary string)
+      def extract_font_program(font)
+        return "" unless font.has_table?("fpgm")
+
+        font_program_data = font.instance_variable_get(:@table_data)["fpgm"]
+        return "" unless font_program_data
+
+        # Return as binary string
+        font_program_data.force_encoding("ASCII-8BIT")
+      rescue StandardError => e
+        warn "Failed to extract font program: #{e.message}"
+        ""
+      end
+
+      # Extract control value program (prep table)
+      #
+      # @param font [TrueTypeFont] TrueType font
+      # @return [String] Control value program bytecode (binary string)
+      def extract_control_value_program(font)
+        return "" unless font.has_table?("prep")
+
+        prep_data = font.instance_variable_get(:@table_data)["prep"]
+        return "" unless prep_data
+
+        # Return as binary string
+        prep_data.force_encoding("ASCII-8BIT")
+      rescue StandardError => e
+        warn "Failed to extract control value program: #{e.message}"
+        ""
+      end
+
+      # Extract control values (cvt table)
+      #
+      # @param font [TrueTypeFont] TrueType font
+      # @return [Array<Integer>] Control values
+      def extract_control_values(font)
+        return [] unless font.has_table?("cvt ")
+
+        cvt_data = font.instance_variable_get(:@table_data)["cvt "]
+        return [] unless cvt_data
+
+        # CVT table is an array of 16-bit signed integers (FWord values)
+        values = []
+        io = StringIO.new(cvt_data)
+        while !io.eof?
+          # Read 16-bit big-endian signed integer
+          bytes = io.read(2)
+          break unless bytes&.length == 2
+
+          value = bytes.unpack1("n") # Unsigned short
+          # Convert to signed
+          value = value - 65536 if value > 32767
+          values << value
+        end
+
+        values
+      rescue StandardError => e
+        warn "Failed to extract control values: #{e.message}"
+        []
+      end
+
+      # Extract per-glyph hints from glyf table
+      #
+      # @param font [TrueTypeFont] TrueType font
+      # @param hint_set [Models::HintSet] Hint set to populate
+      # @return [void]
+      def extract_glyph_hints(font, hint_set)
+        return unless font.has_table?("glyf")
+
+        glyf_table = font.table("glyf")
+        return unless glyf_table
+
+        # Get number of glyphs from maxp table
+        maxp_table = font.table("maxp")
+        return unless maxp_table
+
+        num_glyphs = maxp_table.num_glyphs
+
+        # Iterate through all glyphs
+        (0...num_glyphs).each do |glyph_id|
+          begin
+            glyph = glyf_table.glyph_for(glyph_id)
+            next unless glyph
+            next if glyph.number_of_contours <= 0 # Skip compound glyphs and empty glyphs
+
+            # Extract hints from simple glyph instructions
+            hints = extract(glyph)
+            next if hints.empty?
+
+            # Store glyph hints
+            hint_set.add_glyph_hints(glyph_id, hints)
+          rescue StandardError => e
+            # Skip glyphs that fail to parse
+            next
+          end
+        end
+      rescue StandardError => e
+        warn "Failed to extract glyph hints: #{e.message}"
+      end
     end
   end
 end

data/lib/fontisan/loading_modes.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Fontisan
   # Loading modes module that defines which tables are loaded in each mode.
   #

data/lib/fontisan/models/font_export.rb

@@ -71,8 +71,8 @@ module Fontisan
         attribute :tag, :string
         attribute :checksum, :string
         attribute :parsed, :boolean, default: -> { false }
-        attribute :data, :string, default: -> {}
-        attribute :fields, :string, default: -> {}
+        attribute :data, :string, default: -> { nil }
+        attribute :fields, :string, default: -> { nil }
 
         yaml do
           map "tag", to: :tag

data/lib/fontisan/models/hint.rb

@@ -1,7 +1,135 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Fontisan
   module Models
+    # Container for all font hint data
+    #
+    # This model holds complete hint information from a font including
+    # font-level programs, control values, and per-glyph hints. It provides
+    # a format-agnostic representation that can be converted between
+    # TrueType and PostScript formats.
+    #
+    # @example Creating a HintSet
+    #   hint_set = HintSet.new(
+    #     format: :truetype,
+    #     font_program: fpgm_data,
+    #     control_value_program: prep_data
+    #   )
+    class HintSet
+      # @return [String] Hint format (:truetype or :postscript)
+      attr_accessor :format
+
+      # TrueType font-level hint data
+      # @return [String] Font program (fpgm table) - bytecode executed once
+      attr_accessor :font_program
+
+      # @return [String] Control value program (prep table) - initialization code
+      attr_accessor :control_value_program
+
+      # @return [Array<Integer>] Control values (cvt table) - metrics for hinting
+      attr_accessor :control_values
+
+      # PostScript font-level hint data
+      # @return [String] CFF Private dict hint data (BlueValues, StdHW, etc.) as JSON
+      attr_accessor :private_dict_hints
+
+      # @return [Integer] Number of glyphs with hints
+      attr_accessor :hinted_glyph_count
+
+      # @return [Boolean] Whether hints are present
+      attr_accessor :has_hints
+
+      # Initialize a new HintSet
+      #
+      # @param format [String, Symbol] Hint format (:truetype or :postscript)
+      # @param font_program [String] Font program bytecode
+      # @param control_value_program [String] Control value program bytecode
+      # @param control_values [Array<Integer>] Control values
+      # @param private_dict_hints [String] Private dict hints as JSON
+      # @param hinted_glyph_count [Integer] Number of hinted glyphs
+      # @param has_hints [Boolean] Whether hints are present
+      def initialize(format: nil, font_program: "", control_value_program: "",
+                     control_values: [], private_dict_hints: "{}",
+                     hinted_glyph_count: 0, has_hints: false)
+        @format = format.to_s if format
+        @font_program = font_program || ""
+        @control_value_program = control_value_program || ""
+        @control_values = control_values || []
+        @private_dict_hints = private_dict_hints || "{}"
+        @glyph_hints = "{}"
+        @hinted_glyph_count = hinted_glyph_count
+        @has_hints = has_hints
+      end
+
+      # Add hints for a specific glyph
+      #
+      # @param glyph_id [Integer, String] Glyph identifier
+      # @param hints [Array<Hint>] Hints for the glyph
+      def add_glyph_hints(glyph_id, hints)
+        return if hints.nil? || hints.empty?
+
+        glyph_hints_hash = parse_glyph_hints
+        # Convert Hint objects to hashes for storage
+        hints_data = hints.map do |h|
+          {
+            type: h.type,
+            data: h.data,
+            source_format: h.source_format
+          }
+        end
+        glyph_hints_hash[glyph_id.to_s] = hints_data
+        @glyph_hints = glyph_hints_hash.to_json
+        @hinted_glyph_count = glyph_hints_hash.keys.length
+        @has_hints = true
+      end
+
+      # Get hints for a specific glyph
+      #
+      # @param glyph_id [Integer, String] Glyph identifier
+      # @return [Array<Hint>] Hints for the glyph
+      def get_glyph_hints(glyph_id)
+        glyph_hints_hash = parse_glyph_hints
+        hints_data = glyph_hints_hash[glyph_id.to_s]
+        return [] unless hints_data
+
+        # Reconstruct Hint objects from serialized data
+        hints_data.map { |h| Hint.new(**h.transform_keys(&:to_sym)) }
+      end
+
+      # Get all glyph IDs with hints
+      #
+      # @return [Array<String>] Glyph identifiers
+      def hinted_glyph_ids
+        parse_glyph_hints.keys
+      end
+
+      # Check if empty (no hints)
+      #
+      # @return [Boolean] True if no hints present
+      def empty?
+        !has_hints &&
+          (font_program.nil? || font_program.empty?) &&
+          (control_value_program.nil? || control_value_program.empty?) &&
+          (control_values.nil? || control_values.empty?) &&
+          (private_dict_hints.nil? || private_dict_hints == "{}")
+      end
+
+      private
+
+      # @return [String] Glyph hints as JSON
+      attr_accessor :glyph_hints
+
+      # Parse glyph hints JSON
+      def parse_glyph_hints
+        return {} if @glyph_hints.nil? || @glyph_hints.empty? || @glyph_hints == "{}"
+        JSON.parse(@glyph_hints)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+
     # Universal hint representation supporting both TrueType and PostScript hints
     #
     # Hints are instructions that improve font rendering at small sizes by
@@ -60,16 +188,21 @@ module Fontisan
         case type
         when :stem
           convert_stem_to_truetype
+        when :stem3
+          convert_stem3_to_truetype
         when :flex
           convert_flex_to_truetype
         when :counter
           convert_counter_to_truetype
+        when :hint_replacement
+          convert_hintmask_to_truetype
         when :delta
           # Already in TrueType format
           data[:instructions] || []
         when :interpolate
           # IUP instruction
-          [0x30] # IUP[y], or [0x31] for IUP[x]
+          axis = data[:axis] || :y
+          axis == :x ? [0x31] : [0x30]  # IUP[x] or IUP[y]
         when :shift
           # SHP instruction
           data[:instructions] || []
@@ -80,6 +213,9 @@ module Fontisan
           # Unknown hint type - return empty
           []
         end
+      rescue StandardError => e
+        warn "Error converting hint type #{type} to TrueType: #{e.message}"
+        []
       end
 
       # Convert hint to PostScript hint format
@@ -106,6 +242,9 @@ module Fontisan
           # Unknown hint type
           {}
         end
+      rescue StandardError => e
+        warn "Error converting hint type #{type} to PostScript: #{e.message}"
+        {}
       end
 
       # Check if hint is compatible with target format
@@ -166,6 +305,39 @@ module Fontisan
         []
       end
 
+      # Convert stem3 hint to TrueType instructions
+      def convert_stem3_to_truetype
+        stems = data[:stems] || []
+        orientation = data[:orientation] || :vertical
+
+        # Generate MDAP/MDRP pairs for each stem
+        instructions = []
+
+        stems.each do |stem|
+          if orientation == :vertical
+            # Vertical stem: use Y-axis instructions
+            instructions << 0x2E # MDAP[rnd] - mark reference point
+            instructions << 0xC0 # MDRP[min,rnd,black] - move relative point
+          else
+            # Horizontal stem: use X-axis instructions
+            instructions << 0x2F # MDAP[rnd]
+            instructions << 0xC0 # MDRP[min,rnd,black]
+          end
+        end
+
+        instructions
+      end
+
+      # Convert hintmask hint to TrueType instructions
+      def convert_hintmask_to_truetype
+        # Hintmask controls which hints are active at runtime
+        # TrueType doesn't have a direct equivalent
+        # We can use conditional instructions, but it's complex
+        # For now, return empty and let the main stems handle hinting
+        # TODO: Implement conditional instruction generation if needed
+        []
+      end
+
       # Convert stem hint to PostScript operators
       def convert_stem_to_postscript
         position = data[:position] || 0

data/lib/fontisan/models/validation_report.rb

@@ -29,7 +29,7 @@ module Fontisan
         attribute :severity, :string
         attribute :category, :string
         attribute :message, :string
-        attribute :location, :string, default: -> {}
+        attribute :location, :string, default: -> { nil }
 
         yaml do
           map "severity", to: :severity