fontisan 0.1.0 → 0.2.1

data/lib/fontisan/config/woff2_settings.yml

@@ -0,0 +1,77 @@
+# WOFF2 Encoding Configuration
+#
+# This file defines settings for WOFF2 font encoding, including
+# Brotli compression parameters and table transformation options.
+#
+# Reference: https://www.w3.org/TR/WOFF2/
+
+# Brotli compression settings
+brotli:
+  # Compression quality level (0-11)
+  # Higher values give better compression but slower encoding
+  # Quality 11 is recommended for production web fonts
+  quality: 11
+
+  # Compression mode
+  # :font - Optimized for font data (recommended)
+  # :text - Optimized for text data
+  # :generic - General purpose compression
+  mode: font
+
+# Table transformation settings
+transformations:
+  # Enable table transformations for better compression
+  # For Phase 2 Milestone 2.1: disabled (architecture in place)
+  # Future milestones will enable these for optimization
+  enabled: false
+
+  # Transform glyf and loca tables
+  # Combines glyf and loca into single stream with delta encoding
+  # Typical compression improvement: 20-30%
+  glyf_loca: false
+
+  # Transform hmtx table
+  # Compact representation of horizontal metrics
+  # Typical compression improvement: 10-20%
+  hmtx: false
+
+# Metadata settings
+metadata:
+  # Include font metadata in WOFF2 file
+  include: false
+
+  # Metadata compression
+  compress: true
+
+# Private data settings
+private_data:
+  # Include private data block
+  include: false
+
+# Validation settings
+validation:
+  # Verify checksums after encoding
+  verify_checksums: true
+
+  # Validate WOFF2 structure
+  validate_structure: true
+
+# Optimization settings
+optimization:
+  # Reorder tables for optimal compression
+  # Tables are sorted by tag for consistency
+  reorder_tables: true
+
+  # Remove unnecessary padding
+  minimize_padding: true
+
+# Logging settings
+logging:
+  # Log compression ratios
+  log_compression: true
+
+  # Log table sizes
+  log_table_sizes: false
+
+  # Verbose output
+  verbose: false

data/lib/fontisan/constants.rb

@@ -30,6 +30,15 @@ module Fontisan
     # the checksum adjustment field.
     HEAD_TAG = "head"
 
+    # Hhea table tag identifier (Horizontal Header)
+    HHEA_TAG = "hhea"
+
+    # Hmtx table tag identifier (Horizontal Metrics)
+    HMTX_TAG = "hmtx"
+
+    # Maxp table tag identifier (Maximum Profile)
+    MAXP_TAG = "maxp"
+
     # Name table tag identifier
     NAME_TAG = "name"
 
@@ -60,6 +69,34 @@ module Fontisan
     # Fvar table tag identifier (Font Variations)
     FVAR_TAG = "fvar"
 
+    # Gvar table tag identifier (Glyph Variations for TrueType)
+    GVAR_TAG = "gvar"
+
+    # HVAR table tag identifier (Horizontal Metrics Variations)
+    HVAR_TAG = "HVAR"
+
+    # MVAR table tag identifier (Metrics Variations)
+    MVAR_TAG = "MVAR"
+
+    # VVAR table tag identifier (Vertical Metrics Variations)
+    VVAR_TAG = "VVAR"
+
+    # Cvar table tag identifier (CVT Variations)
+    CVAR_TAG = "cvar"
+
+    # CFF2 table tag identifier (CFF version 2 with variations)
+    CFF2_TAG = "CFF2"
+
+    # TrueType hinting tables
+    # Font Program table (TrueType bytecode executed once at font load)
+    FPGM_TAG = "fpgm"
+
+    # Control Value Program table (TrueType bytecode for initialization)
+    PREP_TAG = "prep"
+
+    # Control Value Table (metrics used by TrueType hinting)
+    CVT_TAG = "cvt "
+
     # Magic number used for font file checksum adjustment calculation.
     # This constant is used in conjunction with the file checksum to compute
     # the checksumAdjustment value stored in the 'head' table.
@@ -74,5 +111,47 @@ module Fontisan
     # All table data in TTF files must be aligned to 4-byte boundaries,
     # with padding added as necessary.
     TABLE_ALIGNMENT = 4
+
+    # Common font subfamily names for string interning
+    #
+    # These strings are frozen and reused to reduce memory allocations
+    # when parsing fonts with common subfamily names.
+    STRING_POOL = {
+      "Regular" => "Regular".freeze,
+      "Bold" => "Bold".freeze,
+      "Italic" => "Italic".freeze,
+      "Bold Italic" => "Bold Italic".freeze,
+      "BoldItalic" => "BoldItalic".freeze,
+      "Light" => "Light".freeze,
+      "Medium" => "Medium".freeze,
+      "Semibold" => "Semibold".freeze,
+      "SemiBold" => "SemiBold".freeze,
+      "Black" => "Black".freeze,
+      "Thin" => "Thin".freeze,
+      "ExtraLight" => "ExtraLight".freeze,
+      "Extra Light" => "Extra Light".freeze,
+      "ExtraBold" => "ExtraBold".freeze,
+      "Extra Bold" => "Extra Bold".freeze,
+      "Heavy" => "Heavy".freeze,
+      "Book" => "Book".freeze,
+      "Roman" => "Roman".freeze,
+      "Normal" => "Normal".freeze,
+      "Oblique" => "Oblique".freeze,
+      "Light Italic" => "Light Italic".freeze,
+      "Medium Italic" => "Medium Italic".freeze,
+      "Semibold Italic" => "Semibold Italic".freeze,
+      "Bold Oblique" => "Bold Oblique".freeze,
+    }.freeze
+
+    # Intern a string using the string pool
+    #
+    # If the string is in the pool, returns the pooled instance.
+    # Otherwise, freezes and returns the original string.
+    #
+    # @param str [String] The string to intern
+    # @return [String] The interned string
+    def self.intern_string(str)
+      STRING_POOL[str] || str.freeze
+    end
   end
 end

data/lib/fontisan/converters/conversion_strategy.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Converters
+    # Interface module for font format conversion strategies
+    #
+    # [`ConversionStrategy`](lib/fontisan/converters/conversion_strategy.rb)
+    # defines the contract that all conversion strategy classes must implement.
+    # This follows the Strategy pattern to enable polymorphic handling of
+    # different conversion types (TTF→OTF, OTF→TTF, same-format copying).
+    #
+    # Each strategy must implement:
+    # - convert(font, options) - Perform the actual conversion
+    # - supported_conversions - Return array of [source, target] format pairs
+    # - validate(font, target_format) - Validate conversion is possible
+    #
+    # Strategies are selected by [`FormatConverter`](lib/fontisan/converters/format_converter.rb)
+    # based on source and target formats.
+    #
+    # @example Implementing a strategy
+    #   class MyStrategy
+    #     include Fontisan::Converters::ConversionStrategy
+    #
+    #     def convert(font, options = {})
+    #       # Perform conversion
+    #       tables = {...}
+    #       tables
+    #     end
+    #
+    #     def supported_conversions
+    #       [[:ttf, :otf], [:otf, :ttf]]
+    #     end
+    #
+    #     def validate(font, target_format)
+    #       # Validate font can be converted
+    #       raise Error unless valid
+    #     end
+    #   end
+    module ConversionStrategy
+      # Convert font to target format
+      #
+      # This method must return a hash of table tags to binary data,
+      # which will be assembled into a complete font by FontWriter.
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Source font
+      # @param options [Hash] Conversion options
+      # @return [Hash<String, String>] Map of table tags to binary data
+      # @raise [NotImplementedError] If not implemented by strategy
+      def convert(font, options = {})
+        raise NotImplementedError,
+              "#{self.class.name} must implement convert(font, options)"
+      end
+
+      # Get list of supported conversions
+      #
+      # Returns an array of [source_format, target_format] pairs that
+      # this strategy can handle.
+      #
+      # @return [Array<Array<Symbol>>] Supported conversion pairs
+      # @raise [NotImplementedError] If not implemented by strategy
+      #
+      # @example
+      #   strategy.supported_conversions
+      #   # => [[:ttf, :otf], [:otf, :ttf]]
+      def supported_conversions
+        raise NotImplementedError,
+              "#{self.class.name} must implement supported_conversions"
+      end
+
+      # Validate that conversion is possible
+      #
+      # Checks if the given font can be converted to the target format.
+      # Should raise an error with a clear message if conversion is not
+      # possible.
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Font to validate
+      # @param target_format [Symbol] Target format (:ttf, :otf, etc.)
+      # @return [Boolean] True if valid
+      # @raise [Error] If conversion is not possible
+      # @raise [NotImplementedError] If not implemented by strategy
+      def validate(font, target_format)
+        raise NotImplementedError,
+              "#{self.class.name} must implement validate(font, target_format)"
+      end
+
+      # Check if strategy supports a conversion
+      #
+      # @param source_format [Symbol] Source format
+      # @param target_format [Symbol] Target format
+      # @return [Boolean] True if supported
+      def supports?(source_format, target_format)
+        supported_conversions.include?([source_format, target_format])
+      end
+    end
+  end
+end

data/lib/fontisan/converters/format_converter.rb

@@ -0,0 +1,408 @@
+# frozen_string_literal: true
+
+require_relative "conversion_strategy"
+require_relative "table_copier"
+require_relative "outline_converter"
+require_relative "woff_writer"
+require_relative "woff2_encoder"
+require_relative "svg_generator"
+require "yaml"
+
+module Fontisan
+  module Converters
+    # Main orchestrator for font format conversions
+    #
+    # [`FormatConverter`](lib/fontisan/converters/format_converter.rb) is the
+    # primary entry point for all format conversion operations. It:
+    # - Selects appropriate conversion strategy based on source/target formats
+    # - Validates conversions against the conversion matrix
+    # - Delegates actual conversion to strategy implementations
+    # - Provides clean error messages for unsupported conversions
+    #
+    # The converter uses a strategy pattern with pluggable strategies for
+    # different conversion types:
+    # - OutlineConverter: TTF ↔ OTF conversions
+    # - TableCopier: Same-format operations
+    # - Woff2Encoder: TTF/OTF → WOFF2 compression
+    # - SvgGenerator: TTF/OTF → SVG font generation
+    #
+    # Supported conversions are defined in the conversion matrix configuration
+    # file, making it easy to extend without modifying code.
+    #
+    # @example Converting TTF to OTF
+    #   converter = Fontisan::Converters::FormatConverter.new
+    #   tables = converter.convert(font, :otf)
+    #   FontWriter.write_to_file(tables, 'output.otf',
+    #                            sfnt_version: 0x4F54544F)
+    #
+    # @example Same-format copy
+    #   converter = Fontisan::Converters::FormatConverter.new
+    #   tables = converter.convert(font, :ttf)  # TTF to TTF
+    #   FontWriter.write_to_file(tables, 'copy.ttf')
+    class FormatConverter
+      # @return [Hash] Conversion matrix loaded from config
+      attr_reader :conversion_matrix
+
+      # @return [Array] Available conversion strategies
+      attr_reader :strategies
+
+      # Initialize converter with strategies
+      #
+      # @param conversion_matrix_path [String, nil] Path to conversion matrix
+      #   config. If nil, uses default.
+      def initialize(conversion_matrix_path: nil)
+        @strategies = [
+          TableCopier.new,
+          OutlineConverter.new,
+          WoffWriter.new,
+          Woff2Encoder.new,
+          SvgGenerator.new,
+        ]
+
+        load_conversion_matrix(conversion_matrix_path)
+      end
+
+      # Convert font to target format
+      #
+      # This is the main entry point for format conversion. It:
+      # 1. Detects source format from font
+      # 2. Validates conversion is supported
+      # 3. Selects appropriate strategy
+      # 4. Delegates conversion to strategy
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Source font
+      # @param target_format [Symbol] Target format (:ttf, :otf, :woff2, :svg)
+      # @param options [Hash] Additional conversion options
+      # @option options [Boolean] :preserve_variation Preserve variation data
+      #   (default: true)
+      # @option options [Boolean] :preserve_hints Preserve rendering hints
+      #   (default: false)
+      # @option options [Hash] :instance_coordinates Coordinates for variable→SVG
+      # @option options [Integer] :instance_index Named instance index for variable→SVG
+      # @return [Hash<String, String>] Map of table tags to binary data
+      # @raise [ArgumentError] If parameters are invalid
+      # @raise [Error] If conversion is not supported
+      #
+      # @example
+      #   tables = converter.convert(font, :otf)
+      #
+      # @example Variable font to SVG at specific weight
+      #   result = converter.convert(variable_font, :svg, instance_coordinates: { "wght" => 700.0 })
+      #
+      # @example Convert with hint preservation
+      #   tables = converter.convert(font, :otf, preserve_hints: true)
+      def convert(font, target_format, options = {})
+        validate_parameters!(font, target_format)
+
+        source_format = detect_format(font)
+        validate_conversion_supported!(source_format, target_format)
+
+        # Special case: Variable font to SVG
+        if variable_font?(font) && target_format == :svg
+          return convert_variable_to_svg(font, options)
+        end
+
+        strategy = select_strategy(source_format, target_format)
+        tables = strategy.convert(font, options.merge(target_format: target_format))
+
+        # Preserve variation data if requested and font is variable
+        if options.fetch(:preserve_variation, true) && variable_font?(font)
+          tables = preserve_variation_data(
+            font,
+            tables,
+            source_format,
+            target_format,
+            options,
+          )
+        end
+
+        tables
+      end
+
+      # Check if a conversion is supported
+      #
+      # @param source_format [Symbol] Source format
+      # @param target_format [Symbol] Target format
+      # @return [Boolean] True if conversion is supported
+      def supported?(source_format, target_format)
+        return false unless conversion_matrix
+
+        conversions = conversion_matrix["conversions"]
+        return false unless conversions
+
+        conversions.any? do |conv|
+          conv["from"] == source_format.to_s &&
+            conv["to"] == target_format.to_s
+        end
+      end
+
+      # Get list of supported target formats for a source format
+      #
+      # @param source_format [Symbol] Source format
+      # @return [Array<Symbol>] Supported target formats
+      def supported_targets(source_format)
+        return [] unless conversion_matrix
+
+        conversions = conversion_matrix["conversions"]
+        return [] unless conversions
+
+        conversions
+          .select { |conv| conv["from"] == source_format.to_s }
+          .map { |conv| conv["to"].to_sym }
+      end
+
+      # Get all supported conversions
+      #
+      # @return [Array<Hash>] Array of conversion hashes with :from and :to
+      def all_conversions
+        return [] unless conversion_matrix
+
+        conversions = conversion_matrix["conversions"]
+        return [] unless conversions
+
+        conversions.map do |conv|
+          { from: conv["from"].to_sym, to: conv["to"].to_sym }
+        end
+      end
+
+      private
+
+      # Convert variable font to SVG at specific coordinates
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Variable font
+      # @param options [Hash] Conversion options
+      # @option options [Hash] :instance_coordinates Design space coordinates
+      # @option options [Integer] :instance_index Named instance index
+      # @return [Hash] Hash with :svg_xml key
+      def convert_variable_to_svg(font, options = {})
+        require_relative "../variation/variable_svg_generator"
+
+        coordinates = options[:instance_coordinates] || {}
+        generator = Variation::VariableSvgGenerator.new(font, coordinates)
+
+        # Use named instance if specified
+        if options[:instance_index]
+          generator.generate_named_instance(options[:instance_index], options)
+        else
+          generator.generate(options)
+        end
+      end
+
+      # Check if font is a variable font
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Font to check
+      # @return [Boolean] True if font has fvar table
+      def variable_font?(font)
+        font.has_table?("fvar")
+      end
+
+      # Preserve variation data from source to target
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Source font
+      # @param tables [Hash<String, String>] Target tables
+      # @param source_format [Symbol] Source format
+      # @param target_format [Symbol] Target format
+      # @param options [Hash] Preservation options
+      # @return [Hash<String, String>] Tables with variation preserved
+      def preserve_variation_data(font, tables, source_format, target_format, options)
+        # Case 1: Compatible formats (same outline format) - just copy tables
+        if compatible_variation_formats?(source_format, target_format)
+          require_relative "../variation/variation_preserver"
+          Variation::VariationPreserver.preserve(font, tables, options)
+
+        # Case 2: Different outline formats - convert variation data
+        elsif convertible_variation_formats?(source_format, target_format)
+          convert_variation_data(font, tables, source_format, target_format, options)
+
+        # Case 3: Unsupported conversion
+        else
+          if options[:preserve_variation]
+            raise Fontisan::Error,
+                  "Cannot preserve variation data for " \
+                  "#{source_format} → #{target_format}"
+          end
+          tables
+        end
+      end
+
+      # Check if formats have compatible variation (same outline format)
+      #
+      # @param source [Symbol] Source format
+      # @param target [Symbol] Target format
+      # @return [Boolean] True if compatible
+      def compatible_variation_formats?(source, target)
+        # Same format (copy operation)
+        return true if source == target
+
+        # Same outline format (just packaging change)
+        (source == :ttf && target == :woff) ||
+          (source == :otf && target == :woff) ||
+          (source == :woff && target == :ttf) ||
+          (source == :woff && target == :otf) ||
+          (source == :ttf && target == :woff2) ||
+          (source == :otf && target == :woff2)
+      end
+
+      # Check if formats allow variation conversion (different outline formats)
+      #
+      # @param source [Symbol] Source format
+      # @param target [Symbol] Target format
+      # @return [Boolean] True if convertible
+      def convertible_variation_formats?(source, target)
+        # Different outline formats (need variation conversion)
+        (source == :ttf && target == :otf) ||
+          (source == :otf && target == :ttf)
+      end
+
+      # Convert variation data between outline formats
+      #
+      # This is a placeholder for full TTF↔OTF variation conversion.
+      # Full implementation would:
+      # 1. Use Variation::Converter to convert gvar ↔ CFF2 blend
+      # 2. Build appropriate variation tables for target format
+      # 3. Preserve common tables (fvar, avar, STAT, metrics)
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Source font
+      # @param tables [Hash<String, String>] Target tables
+      # @param source_format [Symbol] Source format
+      # @param target_format [Symbol] Target format
+      # @param options [Hash] Conversion options
+      # @return [Hash<String, String>] Tables with converted variation
+      def convert_variation_data(font, tables, source_format, target_format, _options)
+        require_relative "../variation/variation_preserver"
+        require_relative "../variation/converter"
+
+        # For now, just preserve common tables and warn about conversion
+        warn "WARNING: Full variation conversion (#{source_format} → " \
+             "#{target_format}) not yet implemented. " \
+             "Preserving common variation tables only."
+
+        # Preserve common tables (fvar, avar, STAT) but not format-specific
+        Variation::VariationPreserver.preserve(
+          font,
+          tables,
+          preserve_format_specific: false,
+          preserve_metrics: true,
+        )
+      end
+
+      # Load conversion matrix from YAML config
+      #
+      # @param path [String, nil] Path to config file
+      def load_conversion_matrix(path)
+        config_path = path || default_conversion_matrix_path
+
+        @conversion_matrix = if File.exist?(config_path)
+                               YAML.load_file(config_path)
+                             else
+                               # Use default inline matrix if file doesn't exist
+                               default_conversion_matrix
+                             end
+      rescue StandardError => e
+        warn "Failed to load conversion matrix: #{e.message}"
+        @conversion_matrix = default_conversion_matrix
+      end
+
+      # Get default conversion matrix path
+      #
+      # @return [String] Path to conversion matrix config
+      def default_conversion_matrix_path
+        File.join(
+          __dir__,
+          "..",
+          "config",
+          "conversion_matrix.yml",
+        )
+      end
+
+      # Get default conversion matrix (fallback)
+      #
+      # @return [Hash] Default conversion matrix
+      def default_conversion_matrix
+        {
+          "conversions" => [
+            { "from" => "ttf", "to" => "ttf" },
+            { "from" => "otf", "to" => "otf" },
+            { "from" => "ttf", "to" => "otf" },
+            { "from" => "otf", "to" => "ttf" },
+          ],
+        }
+      end
+
+      # Validate conversion parameters
+      #
+      # @param font [Object] Font object
+      # @param target_format [Symbol] Target format
+      # @raise [ArgumentError] If parameters are invalid
+      def validate_parameters!(font, target_format)
+        raise ArgumentError, "Font cannot be nil" if font.nil?
+
+        unless font.respond_to?(:table)
+          raise ArgumentError, "Font must respond to :table method"
+        end
+
+        unless target_format.is_a?(Symbol)
+          raise ArgumentError,
+                "target_format must be a Symbol, got: #{target_format.class}"
+        end
+      end
+
+      # Validate conversion is supported
+      #
+      # @param source_format [Symbol] Source format
+      # @param target_format [Symbol] Target format
+      # @raise [Error] If conversion is not supported
+      def validate_conversion_supported!(source_format, target_format)
+        unless supported?(source_format, target_format)
+          available = supported_targets(source_format)
+          message = "Conversion from #{source_format} to #{target_format} " \
+                    "is not supported."
+          message += if available.any?
+                       " Available targets for #{source_format}: " \
+                                  "#{available.join(', ')}"
+                     else
+                       " No conversions available from #{source_format}."
+                     end
+          raise Fontisan::Error, message
+        end
+      end
+
+      # Select conversion strategy
+      #
+      # @param source_format [Symbol] Source format
+      # @param target_format [Symbol] Target format
+      # @return [ConversionStrategy] Selected strategy
+      # @raise [Error] If no strategy supports the conversion
+      def select_strategy(source_format, target_format)
+        strategy = strategies.find do |s|
+          s.supports?(source_format, target_format)
+        end
+
+        unless strategy
+          raise Fontisan::Error,
+                "No strategy available for #{source_format} → #{target_format}"
+        end
+
+        strategy
+      end
+
+      # Detect font format from tables
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Font to detect
+      # @return [Symbol] Format (:ttf or :otf)
+      # @raise [Error] If format cannot be detected
+      def detect_format(font)
+        # Check for CFF/CFF2 tables (OpenType/CFF)
+        if font.has_table?("CFF ") || font.has_table?("CFF2")
+          :otf
+        # Check for glyf table (TrueType)
+        elsif font.has_table?("glyf")
+          :ttf
+        else
+          raise Fontisan::Error,
+                "Cannot detect font format: missing both CFF and glyf tables"
+        end
+      end
+    end
+  end
+end