fontisan 0.1.0 → 0.2.0

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

data/lib/fontisan/woff2/header.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "bindata"
+
+module Fontisan
+  module Woff2
+    # WOFF2 Header structure
+    #
+    # [`Woff2::Header`](lib/fontisan/woff2/header.rb) represents the main
+    # header of a WOFF2 file according to W3C WOFF2 specification.
+    #
+    # The header is more compact than WOFF, using 48 bytes.
+    #
+    # Structure (all big-endian):
+    # - uint32: signature (0x774F4632 'wOF2')
+    # - uint32: flavor (0x00010000 for TTF, 0x4F54544F for CFF)
+    # - uint32: file_length (total WOFF2 file size)
+    # - uint16: numTables (number of font tables)
+    # - uint16: reserved (must be 0)
+    # - uint32: totalSfntSize (uncompressed font size)
+    # - uint32: totalCompressedSize (size of compressed data block)
+    # - uint16: majorVersion (major version of WOFF file)
+    # - uint16: minorVersion (minor version of WOFF file)
+    # - uint32: metaOffset (offset to metadata, 0 if none)
+    # - uint32: metaLength (compressed metadata length)
+    # - uint32: metaOrigLength (uncompressed metadata length)
+    # - uint32: privOffset (offset to private data, 0 if none)
+    # - uint32: privLength (length of private data)
+    #
+    # Reference: https://www.w3.org/TR/WOFF2/#woff20Header
+    #
+    # @example Create a header
+    #   header = Woff2::Header.new
+    #   header.signature = 0x774F4632
+    #   header.flavor = 0x00010000
+    #   header.num_tables = 10
+    class Woff2Header < BinData::Record
+      endian :big
+
+      uint32 :signature         # 'wOF2' magic number
+      uint32 :flavor            # Font format (TTF or CFF)
+      uint32 :file_length       # Total WOFF2 file size
+      uint16 :num_tables        # Number of font tables
+      uint16 :reserved          # Reserved, must be 0
+      uint32 :total_sfnt_size   # Uncompressed font size
+      uint32 :total_compressed_size # Compressed data block size
+      uint16 :major_version     # Major version number
+      uint16 :minor_version     # Minor version number
+      uint32 :meta_offset       # Metadata block offset (0 if none)
+      uint32 :meta_length       # Compressed metadata length
+      uint32 :meta_orig_length  # Uncompressed metadata length
+      uint32 :priv_offset       # Private data offset (0 if none)
+      uint32 :priv_length       # Private data length
+
+      # WOFF2 signature constant
+      SIGNATURE = 0x774F4632 # 'wOF2'
+
+      # Check if signature is valid
+      #
+      # @return [Boolean] True if signature is valid
+      def valid_signature?
+        signature == SIGNATURE
+      end
+
+      # Check if font is TrueType flavored
+      #
+      # @return [Boolean] True if TrueType
+      def truetype?
+        [0x00010000, 0x74727565].include?(flavor) # 'true'
+      end
+
+      # Check if font is CFF flavored
+      #
+      # @return [Boolean] True if CFF/OpenType
+      def cff?
+        flavor == 0x4F54544F # 'OTTO'
+      end
+
+      # Check if metadata is present
+      #
+      # @return [Boolean] True if metadata exists
+      def has_metadata?
+        meta_offset.positive? && meta_length.positive?
+      end
+
+      # Check if private data is present
+      #
+      # @return [Boolean] True if private data exists
+      def has_private_data?
+        priv_offset.positive? && priv_length.positive?
+      end
+
+      # Get header size in bytes
+      #
+      # @return [Integer] Header size (always 48 bytes)
+      def self.header_size
+        48
+      end
+    end
+  end
+end

data/lib/fontisan/woff2/table_transformer.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Woff2
+    # Table transformer for WOFF2 encoding
+    #
+    # [`Woff2::TableTransformer`](lib/fontisan/woff2/table_transformer.rb)
+    # handles table transformations that improve compression in WOFF2.
+    # The WOFF2 spec defines transformations for glyf/loca and hmtx tables.
+    #
+    # For Phase 2 Milestone 2.1:
+    # - Architecture is in place for transformations
+    # - Actual transformation implementations are marked as TODO
+    # - Tables are copied as-is without transformation
+    # - This allows valid WOFF2 generation while leaving room for optimization
+    #
+    # Future milestones will implement:
+    # - glyf/loca transformation (combined stream, delta encoding)
+    # - hmtx transformation (compact representation)
+    #
+    # Reference: https://www.w3.org/TR/WOFF2/#table_tranforms
+    #
+    # @example Transform tables for WOFF2
+    #   transformer = TableTransformer.new(font)
+    #   glyf_data = transformer.transform_table("glyf")
+    class TableTransformer
+      # @return [Object] Font object with table access
+      attr_reader :font
+
+      # Initialize transformer with font
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Source font
+      def initialize(font)
+        @font = font
+      end
+
+      # Transform a table for WOFF2 encoding
+      #
+      # For Milestone 2.1, this returns the original table data
+      # without transformation. The architecture supports future
+      # implementation of actual transformations.
+      #
+      # @param tag [String] Table tag
+      # @return [String, nil] Transformed (or original) table data
+      def transform_table(tag)
+        case tag
+        when "glyf"
+          transform_glyf
+        when "loca"
+          transform_loca
+        when "hmtx"
+          transform_hmtx
+        else
+          # No transformation, return original data
+          get_table_data(tag)
+        end
+      end
+
+      # Check if a table can be transformed
+      #
+      # @param tag [String] Table tag
+      # @return [Boolean] True if table supports transformation
+      def transformable?(tag)
+        %w[glyf loca hmtx].include?(tag)
+      end
+
+      # Determine transformation version for a table
+      #
+      # For Milestone 2.1, always returns TRANSFORM_NONE since
+      # we don't implement transformations yet.
+      #
+      # @param tag [String] Table tag
+      # @return [Integer] Transformation version (0 = none)
+      def transformation_version(_tag)
+        # For this milestone, no transformations are applied
+        Directory::TRANSFORM_NONE
+      end
+
+      private
+
+      # Transform glyf table
+      #
+      # The WOFF2 glyf transformation combines glyf and loca into a
+      # single stream with delta-encoded coordinates and flags.
+      #
+      # TODO: Implement full glyf transformation for better compression.
+      # For now, returns original table data.
+      #
+      # @return [String, nil] Transformed glyf data
+      def transform_glyf
+        # TODO: Implement glyf transformation
+        # This would involve:
+        # 1. Parse all glyphs from glyf table
+        # 2. Combine with loca offsets
+        # 3. Create transformed stream with:
+        #    - nContour values
+        #    - nPoints values
+        #    - Flag bytes (with run-length encoding)
+        #    - x-coordinates (delta-encoded)
+        #    - y-coordinates (delta-encoded)
+        #    - Instruction bytes
+        # 4. Use 255UInt16 encoding for variable-length integers
+        #
+        # Reference: https://www.w3.org/TR/WOFF2/#glyf_table_format
+
+        get_table_data("glyf")
+      end
+
+      # Transform loca table
+      #
+      # In WOFF2, loca is combined with glyf during transformation.
+      # When glyf is transformed, loca table is omitted from output.
+      #
+      # TODO: Implement loca transformation (combined with glyf).
+      # For now, returns original table data.
+      #
+      # @return [String, nil] Transformed loca data
+      def transform_loca
+        # TODO: Implement loca transformation
+        # When glyf transformation is implemented, loca will be:
+        # 1. Combined into the transformed glyf stream
+        # 2. Reconstructed during decompression
+        # 3. Not present as separate table in WOFF2
+
+        get_table_data("loca")
+      end
+
+      # Transform hmtx table
+      #
+      # The WOFF2 hmtx transformation stores advance widths more efficiently
+      # by exploiting redundancy (many glyphs have same advance width).
+      #
+      # TODO: Implement hmtx transformation for better compression.
+      # For now, returns original table data.
+      #
+      # @return [String, nil] Transformed hmtx data
+      def transform_hmtx
+        # TODO: Implement hmtx transformation
+        # This would involve:
+        # 1. Parse hmtx table
+        # 2. Extract common advance widths
+        # 3. Identify proportional vs monospace sections
+        # 4. Use flags to indicate structure
+        # 5. Store only unique advance widths
+        # 6. Store LSB array separately
+        #
+        # Reference: https://www.w3.org/TR/WOFF2/#hmtx_table_format
+
+        get_table_data("hmtx")
+      end
+
+      # Get raw table data from font
+      #
+      # @param tag [String] Table tag
+      # @return [String, nil] Table data or nil if not found
+      def get_table_data(tag)
+        return nil unless font.respond_to?(:table_data)
+
+        font.table_data(tag)
+      end
+    end
+  end
+end