fontisan 0.1.0 → 0.2.1

data/lib/fontisan/variation/variation_preserver.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require_relative "variation_context"
+require_relative "../error"
+
+module Fontisan
+  module Variation
+    # Preserves variation data when converting between compatible font formats
+    #
+    # [`VariationPreserver`](lib/fontisan/variation/variation_preserver.rb)
+    # copies variation tables from source to target font during format
+    # conversion. It handles:
+    # - Common variation tables (fvar, avar, STAT) - shared by all variable fonts
+    # - Format-specific tables (gvar for TTF, CFF2 for OTF)
+    # - Metrics variation tables (HVAR, VVAR, MVAR)
+    # - Table checksum updates
+    # - Validation of table consistency
+    #
+    # **Use Cases:**
+    #
+    # 1. **Variable TTF → Variable WOFF**: Preserve all gvar-based variation
+    # 2. **Variable OTF → Variable WOFF**: Preserve all CFF2-based variation
+    # 3. **Variable TTF → Variable OTF**: Copy common tables (fvar, avar, STAT)
+    #    but variation data conversion handled by Converter
+    # 4. **Variable OTF → Variable TTF**: Copy common tables (fvar, avar, STAT)
+    #    but variation data conversion handled by Converter
+    #
+    # **Preserved Tables:**
+    #
+    # Common (all variable fonts):
+    # - fvar (Font Variations)
+    # - avar (Axis Variations, optional)
+    # - STAT (Style Attributes)
+    #
+    # TrueType-specific:
+    # - gvar (Glyph Variations)
+    # - cvar (CVT Variations, optional)
+    #
+    # CFF2-specific:
+    # - CFF2 (with blend operators)
+    #
+    # Metrics (optional):
+    # - HVAR (Horizontal Metrics Variations)
+    # - VVAR (Vertical Metrics Variations)
+    # - MVAR (Metrics Variations)
+    #
+    # @example Preserve variation when converting TTF to WOFF
+    #   preserver = VariationPreserver.new(ttf_font, woff_tables)
+    #   preserved_tables = preserver.preserve
+    #
+    # @example Preserve only common tables for outline conversion
+    #   preserver = VariationPreserver.new(ttf_font, otf_tables,
+    #                                      preserve_format_specific: false)
+    #   preserved_tables = preserver.preserve
+    class VariationPreserver
+      # Common variation tables present in all variable fonts
+      COMMON_TABLES = %w[fvar avar STAT].freeze
+
+      # TrueType-specific variation tables
+      TRUETYPE_TABLES = %w[gvar cvar].freeze
+
+      # CFF2-specific variation tables
+      CFF2_TABLES = %w[CFF2].freeze
+
+      # Metrics variation tables
+      METRICS_TABLES = %w[HVAR VVAR MVAR].freeze
+
+      # All variation-related tables
+      ALL_VARIATION_TABLES = (COMMON_TABLES + TRUETYPE_TABLES +
+                              CFF2_TABLES + METRICS_TABLES).freeze
+
+      # Preserve variation data from source to target
+      #
+      # @param source_font [TrueTypeFont, OpenTypeFont] Variable font
+      # @param target_tables [Hash<String, String>] Target font tables
+      # @param options [Hash] Preservation options
+      # @return [Hash<String, String>] Tables with variation data preserved
+      def self.preserve(source_font, target_tables, options = {})
+        new(source_font, target_tables, options).preserve
+      end
+
+      # @return [Object] Source font
+      attr_reader :source_font
+
+      # @return [Hash<String, String>] Target tables
+      attr_reader :target_tables
+
+      # @return [Hash] Preservation options
+      attr_reader :options
+
+      # Initialize preserver
+      #
+      # @param source_font [TrueTypeFont, OpenTypeFont] Variable font
+      # @param target_tables [Hash<String, String>] Target font tables
+      # @param options [Hash] Preservation options
+      # @option options [Boolean] :preserve_format_specific Preserve format-
+      #   specific variation tables (default: true)
+      # @option options [Boolean] :preserve_metrics Preserve metrics variation
+      #   tables (default: true)
+      # @option options [Boolean] :validate Validate table consistency
+      #   (default: true)
+      def initialize(source_font, target_tables, options = {})
+        @source_font = source_font
+        @target_tables = target_tables.dup
+        @options = options
+
+        validate_source!
+        @context = VariationContext.new(source_font)
+      end
+
+      # Preserve variation tables
+      #
+      # @return [Hash<String, String>] Target tables with variation preserved
+      def preserve
+        # Copy common variation tables (fvar, avar, STAT)
+        copy_common_tables
+
+        # Copy format-specific variation tables if requested
+        if preserve_format_specific?
+          copy_format_specific_tables
+        end
+
+        # Copy metrics variation tables if requested
+        copy_metrics_tables if preserve_metrics?
+
+        # Validate consistency if requested
+        validate_consistency if validate?
+
+        @target_tables
+      end
+
+      # Check if source font is a variable font
+      #
+      # @return [Boolean] True if source has fvar table
+      def variable_font?
+        @context.variable_font?
+      end
+
+      # Get variation type of source font
+      #
+      # @return [Symbol, nil] :truetype, :cff2, or nil
+      def variation_type
+        @context.variation_type
+      end
+
+      private
+
+      # Validate source font
+      #
+      # @raise [ArgumentError] If source is invalid
+      def validate_source!
+        raise ArgumentError, "Source font cannot be nil" if @source_font.nil?
+
+        unless @source_font.respond_to?(:has_table?) &&
+            @source_font.respond_to?(:table_data)
+          raise ArgumentError,
+                "Source font must respond to :has_table? and :table_data"
+        end
+
+        raise ArgumentError, "Target tables cannot be nil" if @target_tables.nil?
+
+        unless @target_tables.is_a?(Hash)
+          raise ArgumentError,
+                "Target tables must be a Hash, got: #{@target_tables.class}"
+        end
+      end
+
+      # Copy common variation tables (fvar, avar, STAT)
+      #
+      # These tables are independent of outline format and can always be copied
+      def copy_common_tables
+        COMMON_TABLES.each do |tag|
+          copy_table(tag) if @source_font.has_table?(tag)
+        end
+      end
+
+      # Copy format-specific variation tables
+      #
+      # For TrueType: gvar, cvar
+      # For CFF2: CFF2 table
+      def copy_format_specific_tables
+        case variation_type
+        when :truetype
+          copy_truetype_variation_tables
+        when :postscript
+          copy_cff2_variation_tables
+        end
+      end
+
+      # Copy TrueType variation tables
+      def copy_truetype_variation_tables
+        TRUETYPE_TABLES.each do |tag|
+          copy_table(tag) if @source_font.has_table?(tag)
+        end
+      end
+
+      # Copy CFF2 variation tables
+      def copy_cff2_variation_tables
+        # CFF2 table contains both outlines and variation data
+        # Only copy if target doesn't already have CFF2 and source has it
+        return unless @source_font.has_table?("CFF2")
+        return if @target_tables.key?("CFF2")
+
+        copy_table("CFF2")
+      end
+
+      # Copy metrics variation tables (HVAR, VVAR, MVAR)
+      def copy_metrics_tables
+        METRICS_TABLES.each do |tag|
+          copy_table(tag) if @source_font.has_table?(tag)
+        end
+      end
+
+      # Copy a single table from source to target
+      #
+      # @param tag [String] Table tag
+      def copy_table(tag)
+        return unless @source_font.has_table?(tag)
+
+        table_data = @source_font.table_data[tag]
+        return unless table_data
+
+        @target_tables[tag] = table_data.dup
+      end
+
+      # Validate table consistency
+      #
+      # Ensures that copied variation tables are consistent with target font
+      # @raise [Error] If validation fails
+      def validate_consistency
+        # Must have fvar if we're preserving variations
+        unless @target_tables.key?("fvar")
+          raise Fontisan::Error,
+                "Cannot preserve variations: fvar table missing"
+        end
+
+        # If we have gvar, we must have glyf (TrueType outlines)
+        if @target_tables.key?("gvar") && !@target_tables.key?("glyf")
+          raise Fontisan::Error,
+                "Invalid variation preservation: gvar present without glyf"
+        end
+
+        # If we have CFF2, we shouldn't have glyf (CFF2 has CFF outlines)
+        # Check both source and target to catch conflicts
+        has_cff2 = @target_tables.key?("CFF2") ||
+          (@source_font.has_table?("CFF2") && preserve_format_specific?)
+        if has_cff2 && @target_tables.key?("glyf")
+          raise Fontisan::Error,
+                "Invalid variation preservation: CFF2 and glyf both present"
+        end
+
+        # Metrics variation tables require fvar
+        if metrics_tables_present? && !@target_tables.key?("fvar")
+          raise Fontisan::Error,
+                "Metrics variation tables require fvar table"
+        end
+      end
+
+      # Check if any metrics variation tables are present
+      #
+      # @return [Boolean] True if HVAR, VVAR, or MVAR present
+      def metrics_tables_present?
+        METRICS_TABLES.any? { |tag| @target_tables.key?(tag) }
+      end
+
+      # Get preserve_format_specific option
+      #
+      # @return [Boolean] True if format-specific tables should be preserved
+      def preserve_format_specific?
+        @options.fetch(:preserve_format_specific, true)
+      end
+
+      # Get preserve_metrics option
+      #
+      # @return [Boolean] True if metrics tables should be preserved
+      def preserve_metrics?
+        @options.fetch(:preserve_metrics, true)
+      end
+
+      # Get validate option
+      #
+      # @return [Boolean] True if consistency should be validated
+      def validate?
+        @options.fetch(:validate, true)
+      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.1"
 end

data/lib/fontisan/version.rb.orig

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Fontisan
+<<<<<<< HEAD
+  VERSION = "2.0.0"
+=======
+  VERSION = "0.2.0"
+>>>>>>> 4bcec10 (fix: update loading modes)
+end

data/lib/fontisan/woff2/directory.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Woff2
+    # WOFF2 Table Directory Entry
+    #
+    # [`Woff2::Directory`](lib/fontisan/woff2/directory.rb) represents
+    # a single table entry in the WOFF2 table directory. Unlike WOFF,
+    # WOFF2 uses variable-length encoding for sizes and supports table
+    # transformations for better compression.
+    #
+    # Each entry contains:
+    # - flags (1 byte): Contains tag index and transformation version
+    # - tag (0 or 4 bytes): Table tag (omitted if using known tag index)
+    # - origLength (UIntBase128): Original uncompressed table length
+    # - transformLength (UIntBase128, optional): Transformed data length
+    #
+    # Flags byte structure:
+    # - Bits 0-5: Table tag index (0-62 = known tags, 63 = custom tag)
+    # - Bits 6-7: Transformation version
+    #
+    # Reference: https://www.w3.org/TR/WOFF2/#table_dir_format
+    #
+    # @example Create entry for known table
+    #   entry = Directory::Entry.new
+    #   entry.tag = "glyf"
+    #   entry.orig_length = 12000
+    #   entry.flags = entry.calculate_flags
+    #
+    # @example Create entry for custom table
+    #   entry = Directory::Entry.new
+    #   entry.tag = "CUST"
+    #   entry.orig_length = 5000
+    #   entry.flags = 0x3F # Custom tag indicator
+    module Directory
+      # Known table tags with assigned indices (0-62)
+      # Index 63 (0x3F) indicates a custom tag follows
+      KNOWN_TAGS = [
+        "cmap", "head", "hhea", "hmtx", "maxp", "name", "OS/2", "post",
+        "cvt ", "fpgm", "glyf", "loca", "prep", "CFF ", "VORG", "EBDT",
+        "EBLC", "gasp", "hdmx", "kern", "LTSH", "PCLT", "VDMX", "vhea",
+        "vmtx", "BASE", "GDEF", "GPOS", "GSUB", "EBSC", "JSTF", "MATH",
+        "CBDT", "CBLC", "COLR", "CPAL", "SVG ", "sbix", "acnt", "avar",
+        "bdat", "bloc", "bsln", "cvar", "fdsc", "feat", "fmtx", "fvar",
+        "gvar", "hsty", "just", "lcar", "mort", "morx", "opbd", "prop",
+        "trak", "Zapf", "Silf", "Glat", "Gloc", "Feat", "Sill"
+      ].freeze
+
+      # Transformation versions
+      TRANSFORM_NONE = 0
+      TRANSFORM_GLYF_LOCA = 0  # Applied to both glyf and loca
+      TRANSFORM_HMTX = 0       # Applied to hmtx
+
+      # Custom tag indicator
+      CUSTOM_TAG_INDEX = 0x3F
+
+      # WOFF2 Table Directory Entry
+      #
+      # Represents a single table in the WOFF2 font with all metadata
+      # needed for decompression and reconstruction.
+      class Entry
+        attr_accessor :tag, :flags, :orig_length, :transform_length, :offset # Calculated during encoding
+
+        def initialize
+          @tag = nil
+          @flags = 0
+          @orig_length = 0
+          @transform_length = nil
+          @offset = 0
+        end
+
+        # Calculate flags byte for this entry
+        #
+        # @return [Integer] Flags byte (0-255)
+        def calculate_flags
+          tag_index = KNOWN_TAGS.index(tag) || CUSTOM_TAG_INDEX
+          transform_version = determine_transform_version
+
+          # Combine tag index (bits 0-5) and transform version (bits 6-7)
+          (transform_version << 6) | tag_index
+        end
+
+        # Check if table uses a known tag
+        #
+        # @return [Boolean] True if known tag
+        def known_tag?
+          KNOWN_TAGS.include?(tag)
+        end
+
+        # Check if table is transformed
+        #
+        # @return [Boolean] True if transformed
+        def transformed?
+          transform_version != TRANSFORM_NONE && transform_length
+        end
+
+        # Get transformation version from flags
+        #
+        # @return [Integer] Transform version (0-3)
+        def transform_version
+          (flags >> 6) & 0x03
+        end
+
+        # Get tag index from flags
+        #
+        # @return [Integer] Tag index (0-63)
+        def tag_index
+          flags & 0x3F
+        end
+
+        # Determine if this table should be transformed
+        #
+        # For Phase 2 Milestone 2.1, we support transformation flags
+        # but don't implement the actual transformations yet.
+        #
+        # @return [Integer] Transform version
+        def determine_transform_version
+          # For this milestone, we don't apply transformations
+          # but we recognize which tables could be transformed
+          TRANSFORM_NONE
+        end
+
+        # Check if table can be transformed (glyf, loca, hmtx)
+        #
+        # @return [Boolean] True if transformable
+        def transformable?
+          %w[glyf loca hmtx].include?(tag)
+        end
+
+        # Calculate size of this entry when serialized
+        #
+        # @return [Integer] Size in bytes
+        def serialized_size
+          size = 1 # flags byte
+          size += 4 unless known_tag? # custom tag
+          size += uint_base128_size(orig_length)
+          size += uint_base128_size(transform_length) if transformed?
+          size
+        end
+
+        private
+
+        # Estimate size of UIntBase128 encoded value
+        #
+        # @param value [Integer] Value to encode
+        # @return [Integer] Size in bytes (1-5)
+        def uint_base128_size(value)
+          return 1 if value.nil? || value < 128
+
+          bytes = 0
+          v = value
+          while v.positive?
+            bytes += 1
+            v >>= 7
+          end
+          [bytes, 5].min # Max 5 bytes
+        end
+      end
+
+      # Encode an integer as UIntBase128
+      #
+      # Variable-length encoding where:
+      # - If value < 128, use 1 byte
+      # - Otherwise, use high bit to indicate continuation
+      #
+      # @param value [Integer] Value to encode
+      # @return [String] Binary encoded data
+      def self.encode_uint_base128(value)
+        return [value].pack("C") if value < 128
+
+        bytes = []
+        v = value
+
+        # Build bytes from least to most significant
+        loop do
+          bytes.unshift(v & 0x7F)
+          v >>= 7
+          break if v.zero?
+        end
+
+        # Set high bit on all but last byte
+        (0...bytes.length - 1).each do |i|
+          bytes[i] |= 0x80
+        end
+
+        bytes.pack("C*")
+      end
+
+      # Decode UIntBase128 from IO
+      #
+      # @param io [IO] Input stream
+      # @return [Integer] Decoded value
+      # @raise [Error] If encoding is invalid
+      def self.decode_uint_base128(io)
+        result = 0
+        5.times do
+          byte = io.read(1)&.unpack1("C")
+          return nil unless byte
+
+          # Check if high bit is set (continuation)
+          if (byte & 0x80).zero?
+            return (result << 7) | byte
+          else
+            result = (result << 7) | (byte & 0x7F)
+          end
+        end
+
+        # If we're here, encoding is invalid (> 5 bytes)
+        raise Fontisan::Error, "Invalid UIntBase128 encoding"
+      end
+
+      # Encode 255UInt16 value
+      #
+      # Used in transformed glyf table:
+      # - 0-252: value itself (1 byte)
+      # - 253: next byte + 253 (2 bytes)
+      # - 254: next 2 bytes as big-endian (3 bytes)
+      # - 255: next 2 bytes + 506 (3 bytes)
+      #
+      # @param value [Integer] Value to encode (0-65535)
+      # @return [String] Binary encoded data
+      def self.encode_255_uint16(value)
+        if value < 253
+          [value].pack("C")
+        elsif value < 506
+          [253, value - 253].pack("C*")
+        elsif value < 65536
+          [254].pack("C") + [value].pack("n")
+        else
+          [255].pack("C") + [value - 506].pack("n")
+        end
+      end
+
+      # Decode 255UInt16 from IO
+      #
+      # @param io [IO] Input stream
+      # @return [Integer] Decoded value
+      def self.decode_255_uint16(io)
+        first = io.read(1)&.unpack1("C")
+        return nil unless first
+
+        case first
+        when 0..252
+          first
+        when 253
+          second = io.read(1)&.unpack1("C")
+          253 + second
+        when 254
+          io.read(2)&.unpack1("n")
+        when 255
+          value = io.read(2)&.unpack1("n")
+          value + 506
+        end
+      end
+    end
+  end
+end