fontisan 0.2.2 → 0.2.4

data/lib/fontisan/converters/woff2_encoder.rb

@@ -6,7 +6,9 @@ require_relative "../woff2/directory"
 require_relative "../woff2/table_transformer"
 require_relative "../utilities/brotli_wrapper"
 require_relative "../utilities/checksum_calculator"
+require_relative "../validation/woff2_validator"
 require "yaml"
+require "stringio"
 
 module Fontisan
   module Converters
@@ -24,6 +26,7 @@ module Fontisan
     # 5. Compress all tables with single Brotli stream
     # 6. Build WOFF2 header and table directory
     # 7. Assemble complete WOFF2 binary
+    # 8. (Optional) Validate encoded WOFF2
     #
     # For Phase 2 Milestone 2.1:
     # - Basic WOFF2 structure generation
@@ -33,8 +36,13 @@ module Fontisan
     #
     # @example Convert TTF to WOFF2
     #   encoder = Woff2Encoder.new
-    #   woff2_binary = encoder.convert(font)
-    #   File.binwrite('font.woff2', woff2_binary)
+    #   result = encoder.convert(font)
+    #   File.binwrite('font.woff2', result[:woff2_binary])
+    #
+    # @example Convert with validation
+    #   encoder = Woff2Encoder.new
+    #   result = encoder.convert(font, validate: true)
+    #   puts result[:validation_report].text_summary if result[:validation_report]
     class Woff2Encoder
       include ConversionStrategy
 
@@ -57,7 +65,9 @@ module Fontisan
       # @param options [Hash] Conversion options
       # @option options [Integer] :quality Brotli quality (0-11)
       # @option options [Boolean] :transform_tables Apply table transformations
-      # @return [Hash] Hash with :woff2_binary key containing WOFF2 binary
+      # @option options [Boolean] :validate Run validation after encoding
+      # @option options [Symbol] :validation_level Validation level (:strict, :standard, :lenient)
+      # @return [Hash] Hash with :woff2_binary and optional :validation_report keys
       # @raise [Error] If encoding fails
       def convert(font, options = {})
         validate(font, :woff2)
@@ -97,8 +107,16 @@ module Fontisan
         # Assemble WOFF2 binary
         woff2_binary = assemble_woff2(header, entries, compressed_data)
 
-        # Return in special format for ConvertCommand to handle
-        { woff2_binary: woff2_binary }
+        # Prepare result
+        result = { woff2_binary: woff2_binary }
+
+        # Optional validation
+        if options[:validate]
+          validation_report = validate_encoding(woff2_binary, options)
+          result[:validation_report] = validation_report
+        end
+
+        result
       end
 
       # Get list of supported conversions
@@ -144,6 +162,67 @@ module Fontisan
 
       private
 
+      # Validate encoded WOFF2 binary
+      #
+      # @param woff2_binary [String] Encoded WOFF2 data
+      # @param options [Hash] Validation options
+      # @return [Models::ValidationReport] Validation report
+      def validate_encoding(woff2_binary, options)
+        # Load the encoded WOFF2 from memory
+        io = StringIO.new(woff2_binary)
+        woff2_font = Woff2Font.from_file_io(io, "encoded.woff2")
+
+        # Run validation
+        validation_level = options[:validation_level] || :standard
+        validator = Validation::Woff2Validator.new(level: validation_level)
+        validator.validate(woff2_font, "encoded.woff2")
+      rescue StandardError => e
+        # If validation fails, create a report with the error
+        report = Models::ValidationReport.new(
+          font_path: "encoded.woff2",
+          valid: false,
+        )
+        report.add_error("woff2_validation", "Validation failed: #{e.message}", nil)
+        report
+      end
+
+      # Helper method to load WOFF2 from StringIO
+      #
+      # This is added to Woff2Font to support in-memory validation
+      module Woff2FontMemoryLoader
+        def self.from_file_io(io, path_for_report)
+          io.rewind
+
+          woff2 = Woff2Font.new
+          woff2.io_source = Woff2Font::IOSource.new(path_for_report)
+
+          # Read header
+          woff2.header = Woff2::Woff2Header.read(io)
+
+          # Validate signature
+          unless woff2.header.signature == Woff2::Woff2Header::SIGNATURE
+            raise InvalidFontError,
+                  "Invalid WOFF2 signature: expected 0x#{Woff2::Woff2Header::SIGNATURE.to_s(16)}, " \
+                  "got 0x#{woff2.header.signature.to_i.to_s(16)}"
+          end
+
+          # Read table directory
+          woff2.table_entries = Woff2Font.read_table_directory_from_io(io, woff2.header)
+
+          # Decompress tables
+          woff2.decompressed_tables = Woff2Font.decompress_tables(io, woff2.header,
+                                                                   woff2.table_entries)
+
+          # Apply transformations
+          Woff2Font.apply_transformations!(woff2.table_entries, woff2.decompressed_tables)
+
+          woff2
+        end
+      end
+
+      # Extend Woff2Font with in-memory loading
+      Woff2Font.singleton_class.prepend(Woff2FontMemoryLoader)
+
       # Load configuration from YAML file
       #
       # @param path [String, nil] Path to config file
@@ -183,9 +262,9 @@ module Fontisan
             "mode" => "font",
           },
           "transformations" => {
-            "enabled" => false, # Disabled for Milestone 2.1
-            "glyf_loca" => false,
-            "hmtx" => false,
+            "enabled" => true, # Enable transformations for better compression
+            "glyf_loca" => true,
+            "hmtx" => true,
           },
           "metadata" => {
             "include" => false,
@@ -255,11 +334,17 @@ module Fontisan
       # @return [Array<Woff2::Directory::Entry>] Table entries
       def build_table_entries(table_data, transformer, transform_enabled)
         entries = []
+        transformed_data = {}
 
         # Sort tables by tag for consistent output
         sorted_tags = table_data.keys.sort
 
         sorted_tags.each do |tag|
+          # Skip loca if we're transforming glyf (loca is combined with glyf)
+          if tag == "loca" && transform_enabled && transformer.transformable?("glyf")
+            next
+          end
+
           entry = Woff2::Directory::Entry.new
           entry.tag = tag
 
@@ -270,8 +355,10 @@ module Fontisan
           # Apply transformation if enabled and supported
           if transform_enabled && transformer.transformable?(tag)
             transformed = transformer.transform_table(tag)
-            if transformed && transformed.bytesize < data.bytesize
+            if transformed&.bytesize&.positive? && transformed.bytesize < data.bytesize
+              # Transformation successful and reduces size
               entry.transform_length = transformed.bytesize
+              transformed_data[tag] = transformed
             end
           end
 
@@ -281,6 +368,9 @@ module Fontisan
           entries << entry
         end
 
+        # Store transformed data for compression
+        @transformed_data = transformed_data
+
         entries
       end
 
@@ -295,12 +385,15 @@ module Fontisan
         combined_data = String.new(encoding: Encoding::BINARY)
 
         entries.each do |entry|
-          # Get table data
-          data = table_data[entry.tag]
+          # Use transformed data if available, otherwise use original
+          data = if @transformed_data && @transformed_data[entry.tag]
+                   @transformed_data[entry.tag]
+                 else
+                   table_data[entry.tag]
+                 end
+
           next unless data
 
-          # For this milestone, we don't have transformed data yet
-          # Use original table data
           combined_data << data
         end
 

data/lib/fontisan/font_loader.rb

@@ -102,6 +102,37 @@ module Fontisan
     # without extracting individual fonts. Useful for inspecting collection
     # metadata and structure.
     #
+    # = Collection Format Understanding
+    #
+    # Both TTC (TrueType Collection) and OTC (OpenType Collection) files use
+    # the same "ttcf" signature. The distinction between TTC and OTC is NOT
+    # in the collection format itself, but in the fonts contained within:
+    #
+    # - TTC typically contains TrueType fonts (glyf outlines)
+    # - OTC typically contains OpenType fonts (CFF/CFF2 outlines)
+    # - Mixed collections are possible (both TTF and OTF in same collection)
+    #
+    # Each collection can contain multiple SFNT-format font files, with table
+    # deduplication to save space. Individual fonts within a collection are
+    # stored at different offsets within the file, each with their own table
+    # directory and data tables.
+    #
+    # = Detection Strategy
+    #
+    # This method scans ALL fonts in the collection to determine the collection
+    # type accurately:
+    #
+    # 1. Reads all font offsets from the collection header
+    # 2. Examines the sfnt_version of each font in the collection
+    # 3. Counts TrueType fonts (0x00010000 or 0x74727565 "true") vs OpenType fonts (0x4F54544F "OTTO")
+    # 4. If ANY font is OpenType (CFF), returns OpenTypeCollection
+    # 5. Only returns TrueTypeCollection if ALL fonts are TrueType
+    #
+    # This approach correctly handles:
+    # - Homogeneous collections (all TTF or all OTF)
+    # - Mixed collections (both TTF and OTF fonts) - uses OpenTypeCollection
+    # - Large collections with many fonts (like NotoSerifCJK.ttc with 35 fonts)
+    #
     # @param path [String] Path to the collection file
     # @return [TrueTypeCollection, OpenTypeCollection] The collection object
     # @raise [Errno::ENOENT] if file does not exist
@@ -121,23 +152,43 @@ module Fontisan
                 "File is not a collection (TTC/OTC). Use FontLoader.load instead."
         end
 
-        # Read first font offset to detect collection type
-        io.seek(12) # Skip tag (4) + versions (4) + num_fonts (4)
-        first_offset = io.read(4).unpack1("N")
+        # Read version and num_fonts
+        io.seek(8) # Skip tag (4) + version (4)
+        num_fonts = io.read(4).unpack1("N")
+
+        # Read all font offsets
+        font_offsets = num_fonts.times.map { io.read(4).unpack1("N") }
+
+        # Scan all fonts to determine collection type (not just first)
+        truetype_count = 0
+        opentype_count = 0
+
+        font_offsets.each do |offset|
+          io.rewind
+          io.seek(offset)
+          sfnt_version = io.read(4).unpack1("N")
+
+          case sfnt_version
+          when Constants::SFNT_VERSION_TRUETYPE, 0x74727565 # 0x74727565 = 'true'
+            truetype_count += 1
+          when Constants::SFNT_VERSION_OTTO
+            opentype_count += 1
+          else
+            raise InvalidFontError,
+                  "Unknown font type in collection at offset #{offset} (sfnt version: 0x#{sfnt_version.to_s(16)})"
+          end
+        end
 
-        # Peek at first font's sfnt_version
-        io.seek(first_offset)
-        sfnt_version = io.read(4).unpack1("N")
         io.rewind
 
-        case sfnt_version
-        when Constants::SFNT_VERSION_TRUETYPE
-          TrueTypeCollection.from_file(path)
-        when Constants::SFNT_VERSION_OTTO
+        # Determine collection type based on what fonts are inside
+        # If ANY font is OpenType, use OpenTypeCollection (more general format)
+        # Only use TrueTypeCollection if ALL fonts are TrueType
+        if opentype_count > 0
           OpenTypeCollection.from_file(path)
         else
-          raise InvalidFontError,
-                "Unknown font type in collection (sfnt version: 0x#{sfnt_version.to_s(16)})"
+          # All fonts are TrueType
+          TrueTypeCollection.from_file(path)
         end
       end
     end
@@ -167,6 +218,23 @@ module Fontisan
 
     # Load from a collection file (TTC or OTC)
     #
+    # This is the internal method that handles loading individual fonts from
+    # collection files. It reads the collection header to determine the type
+    # (TTC vs OTC) and extracts the requested font.
+    #
+    # = Collection Header Structure
+    #
+    # TTC/OTC files start with:
+    # - Bytes 0-3: "ttcf" tag (4 bytes)
+    # - Bytes 4-7: version (2 bytes major + 2 bytes minor)
+    # - Bytes 8-11: num_fonts (4 bytes, big-endian uint32)
+    # - Bytes 12+: font offset array (4 bytes per font, big-endian uint32)
+    #
+    # CRITICAL: The method seeks to position 8 (after tag and version) to read
+    # num_fonts, NOT position 12 which is where the offset array starts. This
+    # was a bug that caused "Unknown font type" errors when the first offset
+    # was misread as num_fonts.
+    #
     # @param io [IO] Open file handle
     # @param path [String] Path to the collection file
     # @param font_index [Integer] Index of font to extract
@@ -177,7 +245,7 @@ module Fontisan
     def self.load_from_collection(io, path, font_index,
 mode: LoadingModes::FULL, lazy: true)
       # Read collection header to get font offsets
-      io.seek(12) # Skip tag (4) + major_version (2) + minor_version (2) + num_fonts marker (4)
+      io.seek(8) # Skip tag (4) + version (4)
       num_fonts = io.read(4).unpack1("N")
 
       if font_index >= num_fonts
@@ -185,26 +253,41 @@ mode: LoadingModes::FULL, lazy: true)
               "Font index #{font_index} out of range (collection has #{num_fonts} fonts)"
       end
 
-      # Read first offset to detect collection type
-      first_offset = io.read(4).unpack1("N")
+      # Read all font offsets
+      font_offsets = num_fonts.times.map { io.read(4).unpack1("N") }
+
+      # Scan all fonts to determine collection type (not just first)
+      truetype_count = 0
+      opentype_count = 0
+
+      font_offsets.each do |offset|
+        io.rewind
+        io.seek(offset)
+        sfnt_version = io.read(4).unpack1("N")
+
+        case sfnt_version
+        when Constants::SFNT_VERSION_TRUETYPE, 0x74727565 # 0x74727565 = 'true'
+          truetype_count += 1
+        when Constants::SFNT_VERSION_OTTO
+          opentype_count += 1
+        else
+          raise InvalidFontError,
+                "Unknown font type in collection at offset #{offset} (sfnt version: 0x#{sfnt_version.to_s(16)})"
+        end
+      end
 
-      # Peek at first font's sfnt_version to determine TTC vs OTC
-      io.seek(first_offset)
-      sfnt_version = io.read(4).unpack1("N")
       io.rewind
 
-      case sfnt_version
-      when Constants::SFNT_VERSION_TRUETYPE
-        # TrueType Collection
-        ttc = TrueTypeCollection.from_file(path)
-        File.open(path, "rb") { |f| ttc.font(font_index, f, mode: mode) }
-      when Constants::SFNT_VERSION_OTTO
+      # If ANY font is OpenType, use OpenTypeCollection (more general format)
+      # Only use TrueTypeCollection if ALL fonts are TrueType
+      if opentype_count > 0
         # OpenType Collection
         otc = OpenTypeCollection.from_file(path)
         File.open(path, "rb") { |f| otc.font(font_index, f, mode: mode) }
       else
-        raise InvalidFontError,
-              "Unknown font type in collection (sfnt version: 0x#{sfnt_version.to_s(16)})"
+        # TrueType Collection (all fonts are TrueType)
+        ttc = TrueTypeCollection.from_file(path)
+        File.open(path, "rb") { |f| ttc.font(font_index, f, mode: mode) }
       end
     end
 

data/lib/fontisan/formatters/text_formatter.rb

@@ -364,20 +364,36 @@ module Fontisan
       def format_collection_info(info)
         lines = []
 
-        # Header section
-        lines << "=== Collection Information ==="
-        lines << ""
-        lines << "File: #{info.collection_path}"
-        lines << "Format: #{info.collection_format}"
+        # Header section with type and version (like brief mode)
+        lines << "Collection: #{info.collection_path}"
+
+        # Format collection type for display with OpenType version
+        if info.collection_format
+          collection_type_display = case info.collection_format
+                                    when "TTC"
+                                      "TrueType Collection (OpenType 1.4)"
+                                    when "OTC"
+                                      "OpenType Collection (OpenType 1.8)"
+                                    else
+                                      info.collection_format
+                                    end
+          lines << "Type: #{collection_type_display}"
+        end
+
+        lines << "Version: #{info.version_string}"
         lines << "Size: #{format_bytes(info.file_size_bytes)}"
+        lines << "Fonts: #{info.num_fonts}"
         lines << ""
 
-        # Header details
-        lines << "=== Header ==="
-        lines << "Tag: #{info.ttc_tag}"
-        lines << "Version: #{info.version_string} (#{info.version_hex})"
-        lines << "Number of fonts: #{info.num_fonts}"
-        lines << ""
+        # Table sharing statistics
+        if info.table_sharing
+          lines << "=== Table Sharing ==="
+          lines << "Shared tables: #{info.table_sharing.shared_tables}"
+          lines << "Unique tables: #{info.table_sharing.unique_tables}"
+          lines << "Sharing: #{format_float(info.table_sharing.sharing_percentage)}%"
+          lines << "Space saved: #{format_bytes(info.table_sharing.space_saved_bytes)}"
+          lines << ""
+        end
 
         # Font offsets
         lines << "=== Font Offsets ==="
@@ -387,13 +403,35 @@ module Fontisan
         end
         lines << ""
 
-        # Table sharing statistics
-        if info.table_sharing
-          lines << "=== Table Sharing ==="
-          lines << "Shared tables: #{info.table_sharing.shared_tables}"
-          lines << "Unique tables: #{info.table_sharing.unique_tables}"
-          lines << "Sharing: #{format_float(info.table_sharing.sharing_percentage)}%"
-          lines << "Space saved: #{format_bytes(info.table_sharing.space_saved_bytes)}"
+        # Individual font information (like brief mode)
+        if info.fonts && !info.fonts.empty?
+          lines << "=== Fonts ==="
+          lines << ""
+
+          info.fonts.each_with_index do |font_info, index|
+            # Show font index with offset
+            if font_info.collection_offset
+              lines << "Font #{index} (offset: #{font_info.collection_offset}):"
+            else
+              lines << "Font #{index}:"
+            end
+            lines << ""
+
+            # Format each font using same structure as brief mode
+            font_type_display = format_font_type_display(font_info.font_format, font_info.is_variable)
+            add_line(lines, "Font type", font_type_display)
+            add_line(lines, "Family", font_info.family_name)
+            add_line(lines, "Subfamily", font_info.subfamily_name)
+            add_line(lines, "Full name", font_info.full_name)
+            add_line(lines, "PostScript name", font_info.postscript_name)
+            add_line(lines, "Version", font_info.version)
+            add_line(lines, "Vendor ID", font_info.vendor_id)
+            add_line(lines, "Font revision", format_float(font_info.font_revision))
+            add_line(lines, "Units per em", font_info.units_per_em)
+
+            # Blank line between fonts (except after last)
+            lines << "" unless index == info.num_fonts - 1
+          end
         end
 
         lines.join("\n")
@@ -406,8 +444,23 @@ module Fontisan
       def format_collection_brief_info(info)
         lines = []
 
-        # Collection header
+        # Collection header with type and version
         lines << "Collection: #{info.collection_path}"
+
+        # Format collection type for display with OpenType version
+        if info.collection_type
+          collection_type_display = case info.collection_type
+                                    when "TTC"
+                                      "TrueType Collection (OpenType 1.4)"
+                                    when "OTC"
+                                      "OpenType Collection (OpenType 1.8)"
+                                    else
+                                      info.collection_type
+                                    end
+          lines << "Type: #{collection_type_display}"
+        end
+
+        lines << "Version: #{info.collection_version}" if info.collection_version
         lines << "Fonts: #{info.num_fonts}"
         lines << ""
 

data/lib/fontisan/models/bitmap_glyph.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Models
+    # Bitmap glyph representation model
+    #
+    # Represents a bitmap glyph from the CBDT/CBLC tables. Each glyph contains
+    # bitmap image data at a specific ppem size.
+    #
+    # This model uses lutaml-model for structured serialization to YAML/JSON/XML.
+    #
+    # @example Creating a bitmap glyph
+    #   glyph = BitmapGlyph.new
+    #   glyph.glyph_id = 42
+    #   glyph.ppem = 16
+    #   glyph.format = "PNG"
+    #   glyph.width = 16
+    #   glyph.height = 16
+    #   glyph.data_size = 256
+    #
+    # @example Serializing to JSON
+    #   json = glyph.to_json
+    #   # {
+    #   #   "glyph_id": 42,
+    #   #   "ppem": 16,
+    #   #   "format": "PNG",
+    #   #   "width": 16,
+    #   #   "height": 16,
+    #   #   "data_size": 256
+    #   # }
+    class BitmapGlyph < Lutaml::Model::Serializable
+      # @!attribute glyph_id
+      #   @return [Integer] Glyph ID
+      attribute :glyph_id, :integer
+
+      # @!attribute ppem
+      #   @return [Integer] Pixels per em for this bitmap
+      attribute :ppem, :integer
+
+      # @!attribute format
+      #   @return [String] Bitmap format (e.g., "PNG", "JPEG", "TIFF")
+      attribute :format, :string
+
+      # @!attribute width
+      #   @return [Integer] Bitmap width in pixels
+      attribute :width, :integer
+
+      # @!attribute height
+      #   @return [Integer] Bitmap height in pixels
+      attribute :height, :integer
+
+      # @!attribute bit_depth
+      #   @return [Integer] Bit depth (1, 2, 4, 8, 32)
+      attribute :bit_depth, :integer
+
+      # @!attribute data_size
+      #   @return [Integer] Size of bitmap data in bytes
+      attribute :data_size, :integer
+
+      # @!attribute data_offset
+      #   @return [Integer] Offset to bitmap data in CBDT table
+      attribute :data_offset, :integer
+
+      # Check if this is a PNG bitmap
+      #
+      # @return [Boolean] True if format is PNG
+      def png?
+        format&.upcase == "PNG"
+      end
+
+      # Check if this is a JPEG bitmap
+      #
+      # @return [Boolean] True if format is JPEG
+      def jpeg?
+        format&.upcase == "JPEG"
+      end
+
+      # Check if this is a TIFF bitmap
+      #
+      # @return [Boolean] True if format is TIFF
+      def tiff?
+        format&.upcase == "TIFF"
+      end
+
+      # Check if this is a color bitmap (32-bit)
+      #
+      # @return [Boolean] True if 32-bit color
+      def color?
+        bit_depth == 32
+      end
+
+      # Check if this is a monochrome bitmap (1-bit)
+      #
+      # @return [Boolean] True if 1-bit monochrome
+      def monochrome?
+        bit_depth == 1
+      end
+
+      # Get the color depth description
+      #
+      # @return [String] Human-readable color depth
+      def color_depth
+        case bit_depth
+        when 1 then "1-bit (monochrome)"
+        when 2 then "2-bit (4 colors)"
+        when 4 then "4-bit (16 colors)"
+        when 8 then "8-bit (256 colors)"
+        when 32 then "32-bit (full color with alpha)"
+        else "#{bit_depth}-bit"
+        end
+      end
+
+      # Get bitmap dimensions as string
+      #
+      # @return [String] Dimensions in "WxH" format
+      def dimensions
+        "#{width}x#{height}"
+      end
+    end
+  end
+end