fontisan 0.1.0 → 0.2.0

data/lib/fontisan/variation/table_accessor.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Variation
+    # Provides unified table access for variation classes
+    #
+    # This module centralizes table loading logic with optional caching
+    # and consistent error handling. It should be included in variation
+    # classes that need to access font tables.
+    #
+    # @example Using TableAccessor in a variation class
+    #   class MyVariationClass
+    #     include TableAccessor
+    #
+    #     def initialize(font)
+    #       @font = font
+    #       @variation_tables = {}
+    #     end
+    #
+    #     def process
+    #       gvar = variation_table("gvar")
+    #       fvar = require_variation_table("fvar")
+    #     end
+    #   end
+    module TableAccessor
+      # Get a variation table with optional caching
+      #
+      # Loads and optionally caches a font table. Returns nil if table
+      # doesn't exist. Use when table presence is optional.
+      #
+      # @param tag [String] Table tag (e.g., "gvar", "fvar")
+      # @param lazy [Boolean] Enable lazy loading (default: true)
+      # @return [Object, nil] Parsed table object or nil
+      #
+      # @example Get optional table
+      #   gvar = variation_table("gvar")
+      #   return unless gvar
+      def variation_table(tag, lazy: true)
+        # Return cached table if available
+        return @variation_tables[tag] if @variation_tables&.key?(tag)
+
+        # Check table exists
+        return nil unless @font.has_table?(tag)
+
+        # Initialize cache if needed
+        @variation_tables ||= {}
+
+        # Load and cache table
+        @variation_tables[tag] = @font.table(tag)
+      end
+
+      # Get a required variation table
+      #
+      # Loads a table that must exist. Raises error if table is missing.
+      # Use when table presence is required for operation.
+      #
+      # @param tag [String] Table tag
+      # @return [Object] Parsed table object
+      # @raise [MissingVariationTableError] If table doesn't exist
+      #
+      # @example Require table
+      #   fvar = require_variation_table("fvar")
+      #   # Guaranteed to have fvar or error raised
+      def require_variation_table(tag)
+        table = variation_table(tag)
+        return table if table
+
+        raise MissingVariationTableError.new(
+          table: tag,
+          message: "Required variation table '#{tag}' not found in font",
+        )
+      end
+
+      # Check if variation table exists
+      #
+      # @param tag [String] Table tag
+      # @return [Boolean] True if table exists
+      #
+      # @example Check table presence
+      #   if has_variation_table?("gvar")
+      #     # Process gvar
+      #   end
+      def has_variation_table?(tag)
+        @font.has_table?(tag)
+      end
+
+      # Clear variation table cache
+      #
+      # Useful when font tables are modified and need to be reloaded.
+      #
+      # @return [void]
+      def clear_variation_cache
+        @variation_tables&.clear
+      end
+
+      # Clear specific cached table
+      #
+      # @param tag [String] Table tag to clear
+      # @return [void]
+      def clear_variation_table(tag)
+        @variation_tables&.delete(tag)
+      end
+    end
+  end
+end

data/lib/fontisan/variation/validator.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Variation
+    # Validates variable font structure and consistency
+    #
+    # This class performs comprehensive validation of variable font tables
+    # to ensure structural integrity and catch common issues before instance
+    # generation or subsetting operations.
+    #
+    # Validation checks:
+    # 1. Table consistency - Verify axis counts match across tables
+    # 2. Delta integrity - Check delta sets are complete
+    # 3. Region coverage - Ensure regions cover design space
+    # 4. Instance definitions - Validate instance coordinates
+    #
+    # @example Validating a variable font
+    #   validator = Fontisan::Variation::Validator.new(font)
+    #   report = validator.validate
+    #   if report[:valid]
+    #     puts "Font is valid"
+    #   else
+    #     report[:errors].each { |err| puts "Error: #{err}" }
+    #   end
+    class Validator
+      # @return [TrueTypeFont, OpenTypeFont] Font being validated
+      attr_reader :font
+
+      # @return [Array<String>] Validation errors
+      attr_reader :errors
+
+      # @return [Array<String>] Validation warnings
+      attr_reader :warnings
+
+      # Initialize validator
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Variable font to validate
+      def initialize(font)
+        @font = font
+        @errors = []
+        @warnings = []
+      end
+
+      # Perform full validation
+      #
+      # Runs all validation checks and returns a detailed report.
+      #
+      # @return [Hash] Validation report with :valid, :errors, :warnings
+      def validate
+        @errors.clear
+        @warnings.clear
+
+        check_is_variable_font
+        check_table_consistency if @errors.empty?
+        check_delta_integrity if @errors.empty?
+        check_region_coverage if @errors.empty?
+        check_instance_definitions if @errors.empty?
+
+        {
+          valid: @errors.empty?,
+          errors: @errors.dup,
+          warnings: @warnings.dup,
+        }
+      end
+
+      # Quick validation (essential checks only)
+      #
+      # @return [Boolean] True if font passes basic validation
+      def valid?
+        validate[:valid]
+      end
+
+      private
+
+      # Check if font is actually a variable font
+      def check_is_variable_font
+        unless @font.has_table?("fvar")
+          @errors << "Missing required 'fvar' table - not a variable font"
+          return
+        end
+
+        fvar = @font.table("fvar")
+        unless fvar&.axis_count&.positive?
+          @errors << "fvar table has no axes defined"
+        end
+      end
+
+      # Check consistency across all variation tables
+      def check_table_consistency
+        fvar = @font.table("fvar")
+        return unless fvar
+
+        axis_count = fvar.axis_count
+
+        # Check gvar axis count if present
+        if @font.has_table?("gvar")
+          gvar = @font.table("gvar")
+          if gvar && gvar.axis_count != axis_count
+            @errors << "gvar axis count (#{gvar.axis_count}) doesn't match fvar (#{axis_count})"
+          end
+        end
+
+        # Check CFF2 if present
+        if @font.has_table?("CFF2")
+          cff2 = @font.table("CFF2")
+          if cff2.respond_to?(:num_axes)
+            cff2_axes = cff2.num_axes || 0
+            if cff2_axes != axis_count && cff2_axes.positive?
+              @errors << "CFF2 axis count (#{cff2_axes}) doesn't match fvar (#{axis_count})"
+            end
+          end
+        end
+
+        # Check HVAR region count if present
+        check_metrics_table_consistency("HVAR", axis_count)
+        check_metrics_table_consistency("VVAR", axis_count)
+        check_metrics_table_consistency("MVAR", axis_count)
+
+        # Verify at least one variation table exists
+        has_outline_var = @font.has_table?("gvar") || @font.has_table?("CFF2")
+        has_metrics_var = @font.has_table?("HVAR") || @font.has_table?("VVAR") || @font.has_table?("MVAR")
+
+        unless has_outline_var || has_metrics_var
+          @warnings << "No variation tables found (gvar/CFF2/HVAR/VVAR/MVAR)"
+        end
+      end
+
+      # Check metrics table consistency
+      #
+      # @param table_tag [String] Table tag (HVAR, VVAR, MVAR)
+      # @param expected_axes [Integer] Expected axis count
+      def check_metrics_table_consistency(table_tag, expected_axes)
+        return unless @font.has_table?(table_tag)
+
+        table = @font.table(table_tag)
+        return unless table.respond_to?(:item_variation_store)
+
+        store = table.item_variation_store
+        return unless store
+
+        # Check region list axis count
+        if store.respond_to?(:region_list) && store.region_list
+          region_list = store.region_list
+          if region_list.respond_to?(:axis_count)
+            region_axes = region_list.axis_count
+            if region_axes != expected_axes
+              @errors << "#{table_tag} region axis count (#{region_axes}) doesn't match fvar (#{expected_axes})"
+            end
+          end
+        end
+      end
+
+      # Check delta integrity
+      def check_delta_integrity
+        # Check gvar delta completeness
+        if @font.has_table?("gvar") && @font.has_table?("maxp")
+          check_gvar_delta_integrity
+        end
+
+        # Check HVAR delta coverage
+        if @font.has_table?("HVAR")
+          check_hvar_delta_integrity
+        end
+      end
+
+      # Check gvar delta sets are complete
+      def check_gvar_delta_integrity
+        gvar = @font.table("gvar")
+        maxp = @font.table("maxp")
+        return unless gvar && maxp
+
+        glyph_count = maxp.num_glyphs
+        gvar_count = gvar.glyph_count
+
+        if gvar_count != glyph_count
+          @errors << "gvar glyph count (#{gvar_count}) doesn't match maxp (#{glyph_count})"
+        end
+
+        # Sample check: verify first and last glyphs have accessible data
+        if gvar_count.positive?
+          first_data = gvar.glyph_variation_data(0)
+          @warnings << "First glyph has no variation data" if first_data.nil?
+
+          if gvar_count > 1
+            last_data = gvar.glyph_variation_data(gvar_count - 1)
+            @warnings << "Last glyph has no variation data" if last_data.nil?
+          end
+        end
+      rescue StandardError => e
+        @errors << "Failed to check gvar delta integrity: #{e.message}"
+      end
+
+      # Check HVAR delta coverage
+      def check_hvar_delta_integrity
+        hvar = @font.table("HVAR")
+        return unless hvar
+
+        # Check for item_variation_store
+        unless hvar.respond_to?(:item_variation_store)
+          @warnings << "HVAR table doesn't support item_variation_store"
+          return
+        end
+
+        store = hvar.item_variation_store
+        unless store
+          @warnings << "HVAR has no item variation store"
+          return
+        end
+
+        # Check that variation data exists
+        if store.respond_to?(:item_variation_data)
+          data = store.item_variation_data
+          if data.nil? || data.empty?
+            @warnings << "HVAR has no variation data"
+          end
+        end
+      rescue StandardError => e
+        @warnings << "Failed to check HVAR delta integrity: #{e.message}"
+      end
+
+      # Check region coverage
+      def check_region_coverage
+        fvar = @font.table("fvar")
+        return unless fvar
+
+        axes = fvar.axes
+        return if axes.empty?
+
+        # Check gvar regions if present
+        if @font.has_table?("gvar")
+          check_gvar_region_coverage(axes)
+        end
+
+        # Check metrics table regions
+        check_metrics_region_coverage("HVAR", axes) if @font.has_table?("HVAR")
+        check_metrics_region_coverage("VVAR", axes) if @font.has_table?("VVAR")
+        check_metrics_region_coverage("MVAR", axes) if @font.has_table?("MVAR")
+      end
+
+      # Check gvar region coverage
+      #
+      # @param axes [Array] Variation axes
+      def check_gvar_region_coverage(axes)
+        gvar = @font.table("gvar")
+        return unless gvar
+
+        # Check shared tuples are within axis ranges
+        shared = gvar.shared_tuples
+        return if shared.empty?
+
+        shared.each_with_index do |tuple, idx|
+          next unless tuple
+
+          tuple.each_with_index do |coord, axis_idx|
+            next if axis_idx >= axes.length
+            next unless coord
+
+            axes[axis_idx]
+            # Normalized coords should be in [-1, 1] range
+            if coord < -1.0 || coord > 1.0
+              @warnings << "gvar shared tuple #{idx} axis #{axis_idx} out of range: #{coord}"
+            end
+          end
+        end
+      rescue StandardError => e
+        @warnings << "Failed to check gvar region coverage: #{e.message}"
+      end
+
+      # Check metrics table region coverage
+      #
+      # @param table_tag [String] Table tag
+      # @param axes [Array] Variation axes
+      def check_metrics_region_coverage(table_tag, axes)
+        table = @font.table(table_tag)
+        return unless table.respond_to?(:item_variation_store)
+
+        store = table.item_variation_store
+        return unless store.respond_to?(:region_list)
+
+        region_list = store.region_list
+        return unless region_list.respond_to?(:regions)
+
+        # Check each region
+        regions = region_list.regions
+        regions.each_with_index do |region, idx|
+          next unless region.respond_to?(:region_axes)
+
+          region.region_axes.each_with_index do |reg_axis, axis_idx|
+            next if axis_idx >= axes.length
+            next unless reg_axis
+
+            # Check coordinates are in valid range [-1, 1]
+            %i[start_coord peak_coord end_coord].each do |coord_method|
+              next unless reg_axis.respond_to?(coord_method)
+
+              coord = reg_axis.send(coord_method)
+              if coord < -1.0 || coord > 1.0
+                @warnings << "#{table_tag} region #{idx} axis #{axis_idx} #{coord_method} out of range: #{coord}"
+              end
+            end
+          end
+        end
+      rescue StandardError => e
+        @warnings << "Failed to check #{table_tag} region coverage: #{e.message}"
+      end
+
+      # Check instance definitions
+      def check_instance_definitions
+        fvar = @font.table("fvar")
+        return unless fvar
+
+        axes = fvar.axes
+        instances = fvar.instances
+
+        return if instances.empty?
+
+        instances.each_with_index do |instance, idx|
+          next unless instance
+
+          # Check coordinate count matches axis count
+          coords = instance[:coordinates]
+          if coords.length != axes.length
+            @errors << "Instance #{idx} has #{coords.length} coordinates but #{axes.length} axes"
+            next
+          end
+
+          # Check each coordinate is in axis range
+          coords.each_with_index do |coord, axis_idx|
+            axis = axes[axis_idx]
+            next unless axis
+
+            min = axis.min_value
+            max = axis.max_value
+
+            if coord < min || coord > max
+              @warnings << "Instance #{idx} axis #{axis.axis_tag} coordinate #{coord} outside range [#{min}, #{max}]"
+            end
+          end
+        end
+      rescue StandardError => e
+        @errors << "Failed to check instance definitions: #{e.message}"
+      end
+    end
+  end
+end

data/lib/fontisan/variation/variation_context.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require_relative "interpolator"
+require_relative "region_matcher"
+
+module Fontisan
+  module Variation
+    # Provides shared context for variation operations
+    #
+    # This class centralizes the initialization of common variation components
+    # (axes, interpolator, region matcher) that are needed by most variation
+    # operations. It ensures consistent initialization and validation.
+    #
+    # @example Creating a variation context
+    #   context = VariationContext.new(font)
+    #   context.validate!
+    #   puts "Axes: #{context.axes.map(&:axis_tag)}"
+    #
+    # @example Using in a variation class
+    #   class MyGenerator
+    #     def initialize(font)
+    #       @context = VariationContext.new(font)
+    #       @context.validate!
+    #     end
+    #
+    #     def generate
+    #       @context.interpolator.normalize_coordinate(value, "wght")
+    #     end
+    #   end
+    class VariationContext
+      # @return [TrueTypeFont, OpenTypeFont] Font instance
+      attr_reader :font
+
+      # @return [Fvar, nil] fvar table
+      attr_reader :fvar
+
+      # @return [Array<VariationAxisRecord>] Variation axes
+      attr_reader :axes
+
+      # @return [Interpolator] Coordinate interpolator
+      attr_reader :interpolator
+
+      # @return [RegionMatcher] Region matcher
+      attr_reader :region_matcher
+
+      # Initialize variation context
+      #
+      # Loads fvar table and initializes all common variation components.
+      # Does not validate - call validate! explicitly if needed.
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Variable font
+      def initialize(font)
+        @font = font
+        @fvar = font.has_table?("fvar") ? font.table("fvar") : nil
+        @axes = @fvar ? @fvar.axes : []
+        @interpolator = Interpolator.new(@axes)
+        @region_matcher = RegionMatcher.new(@axes)
+      end
+
+      # Validate that font is a proper variable font
+      #
+      # Checks for fvar table and axes definition. Raises errors if
+      # font is not a valid variable font.
+      #
+      # @return [void]
+      # @raise [MissingVariationTableError] If fvar table missing
+      # @raise [InvalidVariationDataError] If no axes defined
+      #
+      # @example Validate before processing
+      #   context = VariationContext.new(font)
+      #   context.validate!
+      #   # Safe to proceed
+      def validate!
+        unless @fvar
+          raise MissingVariationTableError.new(
+            table: "fvar",
+            message: "Font is not a variable font (missing fvar table)",
+          )
+        end
+
+        if @axes.empty?
+          raise InvalidVariationDataError.new(
+            message: "Variable font has no axes defined in fvar table",
+          )
+        end
+      end
+
+      # Check if font is a variable font
+      #
+      # @return [Boolean] True if fvar table exists
+      def variable_font?
+        !@fvar.nil?
+      end
+
+      # Get number of axes
+      #
+      # @return [Integer] Axis count
+      def axis_count
+        @axes.length
+      end
+
+      # Find axis by tag
+      #
+      # @param axis_tag [String] Axis tag (e.g., "wght", "wdth")
+      # @return [VariationAxisRecord, nil] Axis or nil if not found
+      #
+      # @example Find weight axis
+      #   wght_axis = context.find_axis("wght")
+      #   puts "Range: #{wght_axis.min_value} - #{wght_axis.max_value}"
+      def find_axis(axis_tag)
+        @axes.find { |axis| axis.axis_tag == axis_tag }
+      end
+
+      # Get axis tags
+      #
+      # @return [Array<String>] Array of axis tags
+      def axis_tags
+        @axes.map(&:axis_tag)
+      end
+
+      # Validate coordinates against axes
+      #
+      # Checks that all coordinate values are within valid axis ranges.
+      #
+      # @param coordinates [Hash<String, Float>] Design space coordinates
+      # @return [void]
+      # @raise [InvalidCoordinatesError] If any coordinate out of range
+      #
+      # @example Validate coordinates
+      #   context.validate_coordinates({ "wght" => 700 })
+      def validate_coordinates(coordinates)
+        coordinates.each do |axis_tag, value|
+          axis = find_axis(axis_tag)
+
+          unless axis
+            raise InvalidCoordinatesError.new(
+              axis: axis_tag,
+              value: value,
+              range: [],
+              message: "Unknown axis '#{axis_tag}'",
+            )
+          end
+
+          if value < axis.min_value || value > axis.max_value
+            raise InvalidCoordinatesError.new(
+              axis: axis_tag,
+              value: value,
+              range: [axis.min_value, axis.max_value],
+              message: "Coordinate #{value} for axis '#{axis_tag}' outside valid range [#{axis.min_value}, #{axis.max_value}]",
+            )
+          end
+        end
+      end
+
+      # Get default coordinates
+      #
+      # Returns coordinates at default values for all axes.
+      #
+      # @return [Hash<String, Float>] Default coordinates
+      def default_coordinates
+        coordinates = {}
+        @axes.each do |axis|
+          coordinates[axis.axis_tag] = axis.default_value
+        end
+        coordinates
+      end
+
+      # Normalize coordinates to [-1, 1] range
+      #
+      # Convenience method that delegates to interpolator.
+      #
+      # @param coordinates [Hash<String, Float>] User-space coordinates
+      # @return [Hash<String, Float>] Normalized coordinates
+      def normalize_coordinates(coordinates)
+        @interpolator.normalize_coordinates(coordinates)
+      end
+
+      # Get variation type
+      #
+      # Determines whether font uses TrueType (gvar) or PostScript (CFF2)
+      # variation format.
+      #
+      # @return [Symbol] :truetype, :postscript, or :none
+      def variation_type
+        if @font.has_table?("CFF2")
+          :postscript
+        elsif @font.has_table?("gvar")
+          :truetype
+        else
+          :none
+        end
+      end
+
+      # Check if font has glyph variations
+      #
+      # @return [Boolean] True if gvar or CFF2 present
+      def has_glyph_variations?
+        @font.has_table?("gvar") || @font.has_table?("CFF2")
+      end
+
+      # Check if font has metrics variations
+      #
+      # @return [Boolean] True if HVAR, VVAR, or MVAR present
+      def has_metrics_variations?
+        @font.has_table?("HVAR") ||
+          @font.has_table?("VVAR") ||
+          @font.has_table?("MVAR")
+      end
+    end
+  end
+end

data/lib/fontisan/version.rb

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