fontisan 0.4.12 → 0.4.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e97f99deb241e5abd1bbdaeb27849efb3a4597bf2139fc8a1fa815fcccbfdfcb
-  data.tar.gz: ced71eac0e00e479581c5460e33672aa80ded30cd40cb590b5a09621c5441290
+  metadata.gz: 9f871e8b123fcb90294e234b49a73ee6ad5541a5064c11e34b47cf8a0c26646a
+  data.tar.gz: 90fb63c4e71aaf2bb91f4884f3b6cdca26b5b9bbb9dac3f0a812d96bca5d69f8
 SHA512:
-  metadata.gz: cc72fc9f58560fddf2440ecead8a54060a06a6da38ac3de2212d893cb3dbb2dea88649c82c30ff8fb10d25389058a63770d4309e414856f031ab3d88659f4150
-  data.tar.gz: bac0c91aa712516256d2ae7fb7ccee7dd31fe1549ace5bb533ea9d2b27b7087da4b0b200412794b3677b44c43bae79c87cbcaa849db3f6d993d00dac91a1e3a3
+  metadata.gz: 57fc98bbeb302426ef4fcf5453c0c37102ee6cf41c126d4cd724a727ffaee24313b6faf9a0ae1301642eefa85b93bca4371853a7891df304ac5c191c88a77aac
+  data.tar.gz: 4cbc0c95aa3eff13ed3dd479450d3615cf1a01f5e6a5e866c9f98b216491b14d92885178f4e03f23879a0eedcdffa03b8bb74653d5df39ab8d1a776f51d3cbcf

data/lib/fontisan/converters/woff2_encoder.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# Validation temporarily disabled - will be reimplemented with new DSL framework in Week 3+
-# require_relative "../validation/woff2_validator"
 require "yaml"
 require "stringio"
 
@@ -17,27 +15,16 @@ module Fontisan
     # 1. Load configuration settings
     # 2. Determine font flavor (TTF or CFF)
     # 3. Collect and order tables
-    # 4. Transform tables (placeholder for glyf/loca/hmtx optimization)
-    # 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
-    # - Brotli compression of table data
-    # - Valid WOFF2 files for web font delivery
-    # - Table transformations are architectural placeholders
+    # 4. Apply WOFF2 spec encoder rules (drop DSIG, mark head.flags)
+    # 5. Transform tables (placeholder for glyf/loca/hmtx optimization)
+    # 6. Compress all tables with single Brotli stream
+    # 7. Build WOFF2 header and table directory
+    # 8. Assemble complete WOFF2 binary
     #
     # @example Convert TTF to WOFF2
     #   encoder = Woff2Encoder.new
     #   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
 
@@ -64,12 +51,11 @@ module Fontisan
 
       # Convert font to WOFF2 format.
       #
-      # Returns a hash with `:woff2_binary` containing the complete WOFF2 file.
-      #
       # @param font [TrueTypeFont, OpenTypeFont] Source font
       # @param options [Hash{Symbol => Object}] Per-call options:
       #   - `:brotli_quality` (0–11, default from config or 11)
-      #   - `:transform_tables` (bool, default false)
+      #   - `:transform_tables` (bool, default false; glyf/loca are always
+      #     transformed per WOFF2 spec section 5.3 regardless of this flag)
       #   - `:quality` — legacy alias for `:brotli_quality` (backward compat)
       # @return [Hash{Symbol => String}] `{ woff2_binary: <bytes> }`
       # @raise [ArgumentError] if any option fails validation
@@ -84,47 +70,32 @@ module Fontisan
           config["brotli"]["quality"]
         end
 
-        # Detect font flavor
         flavor = detect_flavor(font)
-
-        # Collect all tables
         table_data = collect_tables(font, options)
+        Woff2::EncoderRules.apply!(table_data)
+
+        glyf_transform = apply_glyf_loca_transform!(table_data, font)
 
-        # Transform tables (if enabled)
         transformer = Woff2::TableTransformer.new(font)
         transform_enabled = resolved.fetch(:transform_tables, false)
+        entries, transformed_data = build_table_entries(table_data,
+                                                        transformer,
+                                                        transform_enabled,
+                                                        glyf_transform:)
 
-        # Build table directory entries
-        entries = build_table_entries(table_data, transformer,
-                                      transform_enabled)
-
-        # Compress all table data into single stream
-        compressed_data = compress_tables(entries, table_data, quality)
-
-        # Calculate sizes
-        total_sfnt_size = calculate_sfnt_size(table_data)
-        total_compressed_size = compressed_data.bytesize
+        compressed_data = compress_tables(entries, table_data,
+                                          transformed_data, quality)
 
-        # Build WOFF2 header
+        total_sfnt_size = calculate_sfnt_size(table_data,
+                                              glyf_transform:)
         header = build_header(
           flavor: flavor,
           num_tables: entries.size,
           total_sfnt_size: total_sfnt_size,
-          total_compressed_size: total_compressed_size,
+          total_compressed_size: compressed_data.bytesize,
         )
 
-        # Assemble WOFF2 binary
-        woff2_binary = assemble_woff2(header, entries, compressed_data)
-
-        # Prepare result
-        { woff2_binary: woff2_binary }
-
-        # Optional validation
-        # Temporarily disabled - will be reimplemented with new DSL framework
-        # if options[:validate]
-        #   validation_report = validate_encoding(woff2_binary, options)
-        #   result[:validation_report] = validation_report
-        # end
+        { woff2_binary: assemble_woff2(header, entries, compressed_data) }
       end
 
       # Get list of supported conversions
@@ -150,7 +121,6 @@ module Fontisan
                 "got: #{target_format}"
         end
 
-        # Verify font has required tables
         required_tables = %w[head hhea maxp]
         required_tables.each do |tag|
           unless font.table(tag)
@@ -159,7 +129,6 @@ module Fontisan
           end
         end
 
-        # Verify font has either glyf or CFF table
         unless font.has_table?("glyf") || font.has_table?("CFF ") || font.has_table?("CFF2")
           raise Fontisan::Error,
                 "Font must have either glyf or CFF/CFF2 table"
@@ -170,51 +139,10 @@ module Fontisan
 
       private
 
-      # 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)
-
       # Normalize legacy `:quality` option to `:brotli_quality`.
+      #
       # Internal callers and older specs use `:quality`; the public DSL uses
       # `:brotli_quality`. Returns a new hash; does not mutate the input.
-      #
-      # @param options [Hash]
-      # @return [Hash]
       def normalize_legacy_quality(options)
         return options unless options.key?(:quality) && !options.key?(:brotli_quality)
 
@@ -222,18 +150,11 @@ module Fontisan
       end
 
       # Slice options to those declared by this strategy.
-      #
-      # @param options [Hash]
-      # @return [Hash]
       def strategy_options(options)
         names = self.class.supported_options.to_set(&:name)
         options.select { |k, _| names.include?(k.to_sym) }
       end
 
-      # Load configuration from YAML file
-      #
-      # @param path [String, nil] Path to config file
-      # @return [Hash] Configuration settings
       def load_configuration(path)
         config_path = path || default_config_path
 
@@ -247,21 +168,10 @@ module Fontisan
         default_configuration
       end
 
-      # Get default configuration path
-      #
-      # @return [String] Path to config file
       def default_config_path
-        File.join(
-          __dir__,
-          "..",
-          "config",
-          "woff2_settings.yml",
-        )
+        File.join(__dir__, "..", "config", "woff2_settings.yml")
       end
 
-      # Get default configuration
-      #
-      # @return [Hash] Default settings
       def default_configuration
         {
           "brotli" => {
@@ -269,7 +179,7 @@ module Fontisan
             "mode" => "font",
           },
           "transformations" => {
-            "enabled" => true, # Enable transformations for better compression
+            "enabled" => true,
             "glyf_loca" => true,
             "hmtx" => true,
           },
@@ -279,10 +189,6 @@ module Fontisan
         }
       end
 
-      # Detect font flavor (TTF or CFF)
-      #
-      # @param font [TrueTypeFont, OpenTypeFont] Font to detect
-      # @return [Integer] Flavor value
       def detect_flavor(font)
         if font.has_table?("CFF ") || font.has_table?("CFF2")
           0x4F54544F # 'OTTO' for CFF
@@ -294,36 +200,59 @@ module Fontisan
         end
       end
 
-      # Collect all tables from font
+      # Collect all tables from font.
       #
-      # @param font [TrueTypeFont, OpenTypeFont] Source font
-      # @param options [Hash] Conversion options
-      # @return [Hash<String, String>] Map of tag to table data
+      # Spec-mandated exclusions (DSIG) and adjustments (head.flags bit 11)
+      # are applied by `Woff2::EncoderRules`, not here — this method is a
+      # pure reader.
       def collect_tables(font, _options = {})
-        tables = {}
-
-        # Get all table names from font
         table_names = if font.respond_to?(:table_names)
                         font.table_names
                       else
-                        # Fallback: try common tables
                         %w[head hhea maxp OS/2 name cmap post hmtx glyf loca
                            CFF]
                       end
 
-        table_names.each do |tag|
+        table_names.each_with_object({}) do |tag, tables|
           data = get_table_data(font, tag)
           tables[tag] = data if data && !data.empty?
         end
-
-        tables
       end
 
-      # Get table data from font
+      # Apply the WOFF2 glyf/loca paired transform per spec section 5.1/5.3.
       #
-      # @param font [Object] Font object
-      # @param tag [String] Table tag
-      # @return [String, nil] Table data
+      # Returns a hash with the transformed glyf bytes and the original
+      # loca length needed to emit its synthetic directory entry, or nil
+      # for CFF fonts or fonts missing glyf/loca. The original glyf bytes
+      # are kept in `table_data` so its `origLength` is preserved; the
+      # transformed bytes are passed to the entries builder separately.
+      #
+      # @return [Hash{Symbol => Object}, nil]
+      def apply_glyf_loca_transform!(table_data, font)
+        return nil unless font.respond_to?(:has_table?)
+        return nil unless font.has_table?("glyf") && font.has_table?("loca")
+
+        glyf_data = table_data["glyf"]
+        loca_data = table_data["loca"]
+        return nil unless glyf_data && loca_data
+
+        maxp = font.table("maxp")
+        head = font.table("head")
+        return nil unless maxp && head
+
+        transformed = Woff2::GlyfLocaTransform.new(
+          glyf_data:,
+          loca_data:,
+          num_glyphs: maxp.num_glyphs,
+          index_format: head.index_to_loc_format,
+        ).transform
+
+        loca_orig_length = loca_data.bytesize
+        table_data.delete("loca")
+
+        { transformed_glyf: transformed, loca_orig_length: }
+      end
+
       def get_table_data(font, tag)
         if font.respond_to?(:table_data)
           font.table_data[tag]
@@ -333,119 +262,125 @@ module Fontisan
         end
       end
 
-      # Build table directory entries
+      # Build table directory entries.
+      #
+      # When `glyf_transform` is provided, glyf gets a transformLength entry
+      # (transformed bytes via Woff2::GlyfLocaTransform) and a synthetic
+      # loca entry follows glyf per spec section 5.5 with transformLength=0.
       #
-      # @param table_data [Hash<String, String>] Table data map
-      # @param transformer [Woff2::TableTransformer] Table transformer
-      # @param transform_enabled [Boolean] Enable transformations
-      # @return [Array<Woff2::Directory::Entry>] Table entries
-      def build_table_entries(table_data, transformer, transform_enabled)
+      # @return [Array(Array<Entry>, Hash<String, String>)]
+      #   Pair of entries and the transformed-by-tag data map.
+      def build_table_entries(table_data, transformer, transform_enabled,
+                              glyf_transform: nil)
         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
+        table_data.keys.sort.each do |tag|
+          if tag == "glyf" && glyf_transform
+            entries << build_glyf_entry(table_data["glyf"],
+                                        glyf_transform[:transformed_glyf])
+            entries << build_loca_entry(glyf_transform[:loca_orig_length])
+            transformed_data["glyf"] = glyf_transform[:transformed_glyf]
+          else
+            entry = build_entry(tag:, data: table_data[tag], transformer:,
+                                transform_enabled:, transformed_data:)
+            entries << entry if entry
           end
+        end
 
-          entry = Woff2::Directory::Entry.new
-          entry.tag = tag
-
-          # Get original table data
-          data = table_data[tag]
-          entry.orig_length = data.bytesize
-
-          # Apply transformation if enabled and supported
-          if transform_enabled && transformer.transformable?(tag)
-            transformed = transformer.transform_table(tag)
-            if transformed&.bytesize&.positive? && transformed.bytesize < data.bytesize
-              # Transformation successful and reduces size
-              entry.transform_length = transformed.bytesize
-              transformed_data[tag] = transformed
-            end
-          end
+        [entries, transformed_data]
+      end
 
-          # Calculate flags
-          entry.flags = entry.calculate_flags
+      def build_entry(tag:, data:, transformer:, transform_enabled:,
+                      transformed_data:)
+        return nil unless data
 
-          entries << entry
+        # loca is combined into glyf during transformation.
+        return nil if tag == "loca" && transform_enabled && transformer.transformable?("glyf")
+
+        entry = Woff2::Directory::Entry.new
+        entry.tag = tag
+        entry.orig_length = data.bytesize
+
+        if transform_enabled && transformer.transformable?(tag) && tag != "glyf" && tag != "loca"
+          transformed = transformer.transform_table(tag)
+          if transformed&.bytesize&.positive? && transformed.bytesize < data.bytesize
+            entry.transform_length = transformed.bytesize
+            transformed_data[tag] = transformed
+          end
         end
 
-        # Store transformed data for compression
-        @transformed_data = transformed_data
+        entry.flags = entry.calculate_flags
+        entry
+      end
+
+      # Build the glyf directory entry. origLength is the original (input)
+      # glyf size; transformLength is the size of the WOFF2-transformed
+      # glyf stream per spec section 5.1.
+      def build_glyf_entry(orig_data, transformed_data)
+        entry = Woff2::Directory::Entry.new
+        entry.tag = "glyf"
+        entry.orig_length = orig_data.bytesize
+        entry.transform_length = transformed_data.bytesize
+        entry.flags = entry.calculate_flags
+        entry
+      end
 
-        entries
+      # Build the synthetic loca directory entry for transformed glyf/loca.
+      # Per spec section 5.3, transformLength MUST be 0 and the data is
+      # omitted from the brotli-compressed block.
+      def build_loca_entry(orig_length)
+        entry = Woff2::Directory::Entry.new
+        entry.tag = "loca"
+        entry.orig_length = orig_length
+        entry.transform_length = 0
+        entry.flags = entry.calculate_flags
+        entry
       end
 
-      # Compress all tables into single Brotli stream
-      #
-      # @param entries [Array<Woff2::Directory::Entry>] Table entries
-      # @param table_data [Hash<String, String>] Original table data
-      # @param quality [Integer] Brotli quality
-      # @return [String] Compressed data
-      def compress_tables(entries, table_data, quality)
-        # Concatenate all table data in entry order
+      def compress_tables(entries, table_data, transformed_data, quality)
         combined_data = String.new(encoding: Encoding::BINARY)
 
         entries.each do |entry|
-          # 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
-
+          data = transformed_data[entry.tag] || table_data[entry.tag]
           next unless data
 
           combined_data << data
         end
 
-        # Compress with Brotli
-        Utilities::BrotliWrapper.compress(
-          combined_data,
-          quality: quality,
-        )
+        Utilities::BrotliWrapper.compress(combined_data, quality: quality)
       end
 
-      # Calculate total SFNT size (uncompressed)
+      # Calculate total SFNT size (uncompressed) per spec.
       #
-      # @param table_data [Hash<String, String>] Table data map
-      # @return [Integer] Total size in bytes
-      def calculate_sfnt_size(table_data)
-        # Header size (offset table)
-        size = 12
-
-        # Table directory size
-        size += table_data.size * 16
+      # When glyf/loca are transformed, loca's data is omitted from the
+      # brotli-compressed block but is reconstructed by the decoder. The
+      # SFNT size still includes the reconstructed loca table.
+      def calculate_sfnt_size(table_data, glyf_transform: nil)
+        size = 12 # offset table
+        size += table_data.size * 16 # table directory
+        size += 16 if glyf_transform # synthetic loca directory entry
 
-        # Table data size (with padding)
         table_data.each_value do |data|
           size += data.bytesize
-          # Add padding to 4-byte boundary
-          padding = (4 - (data.bytesize % 4)) % 4
-          size += padding
+          size += (4 - (data.bytesize % 4)) % 4 # pad to 4-byte boundary
+        end
+
+        if glyf_transform
+          loca_len = glyf_transform[:loca_orig_length]
+          size += loca_len
+          size += (4 - (loca_len % 4)) % 4
         end
 
         size
       end
 
-      # Build WOFF2 header
-      #
-      # @param flavor [Integer] Font flavor
-      # @param num_tables [Integer] Number of tables
-      # @param total_sfnt_size [Integer] Uncompressed size
-      # @param total_compressed_size [Integer] Compressed size
-      # @return [Woff2::Woff2Header] WOFF2 header
       def build_header(flavor:, num_tables:, total_sfnt_size:,
-total_compressed_size:)
+                       total_compressed_size:)
         header = Woff2::Woff2Header.new
         header.signature = Woff2::Woff2Header::SIGNATURE
         header.flavor = flavor
-        header.file_length = 0 # Will be updated later
+        header.file_length = 0 # updated by update_woff2_length!
         header.num_tables = num_tables
         header.reserved = 0
         header.total_sfnt_size = total_sfnt_size
@@ -457,59 +392,29 @@ total_compressed_size:)
         header.meta_orig_length = 0
         header.priv_offset = 0
         header.priv_length = 0
-
         header
       end
 
-      # Assemble complete WOFF2 binary
-      #
-      # @param header [Woff2::Woff2Header] WOFF2 header
-      # @param entries [Array<Woff2::Directory::Entry>] Table entries
-      # @param compressed_data [String] Compressed table data
-      # @return [String] Complete WOFF2 binary
       def assemble_woff2(header, entries, compressed_data)
         woff2_data = String.new(encoding: Encoding::BINARY)
+        woff2_data << header.to_binary_s
 
-        # Write header (placeholder, we'll update file_length later)
-        header_binary = header.to_binary_s
-        woff2_data << header_binary
-
-        # Write table directory
         entries.each do |entry|
           woff2_data << [entry.flags].pack("C")
-
-          # Write custom tag if needed
-          unless entry.known_tag?
-            woff2_data << entry.tag.ljust(4, "\x00")
-          end
-
-          # Write orig_length (UIntBase128)
+          woff2_data << entry.tag.ljust(4, "\x00") unless entry.known_tag?
           woff2_data << Woff2::Directory.encode_uint_base128(entry.orig_length)
-
-          # Write transform_length if present
           if entry.transformed?
             woff2_data << Woff2::Directory.encode_uint_base128(entry.transform_length)
           end
         end
 
-        # Write compressed data
         woff2_data << compressed_data
-
-        # Update header file_length field
         update_woff2_length!(woff2_data)
-
         woff2_data
       end
 
-      # Update WOFF2 file length in header
-      #
-      # @param woff2_data [String] WOFF2 binary (modified in place)
-      # @return [void]
       def update_woff2_length!(woff2_data)
-        total_length = woff2_data.bytesize
-
-        # file_length field is at offset 8 in header (uint32)
-        woff2_data[8, 4] = [total_length].pack("N")
+        woff2_data[8, 4] = [woff2_data.bytesize].pack("N")
       end
     end
   end

data/lib/fontisan/sfnt_font.rb

@@ -431,9 +431,14 @@ module Fontisan
 
     # Get list of all table tags (cached for performance)
     #
-    # @return [Array<String>] Array of table tag strings
+    # Returns plain UTF-8 Ruby Strings, not BinData::String instances —
+    # callers can rely on `eql?`/`==`/Hash lookup working against literal
+    # strings. BinData::String is encoding-sensitive and breaks Hash key
+    # comparison silently.
+    #
+    # @return [Array<String>] Array of table tag strings (UTF-8)
     def table_names
-      @table_names ||= tables.map(&:tag)
+      @table_names ||= tables.map { |entry| normalize_tag(entry.tag) }
     end
 
     # Get OOP SfntTable instance for a table

data/lib/fontisan/tables/head.rb

@@ -18,6 +18,16 @@ module Fontisan
       # Magic number that must be present in the head table
       MAGIC_NUMBER = 0x5F0F3CF5
 
+      # Bit flags for the `flags` field (uint16), per OpenType spec.
+      # Only bits we currently reference are named here; see the OpenType
+      # `head` table specification for the full list.
+      #
+      # Bit 11 indicates the font data has been losslessly modified
+      # (e.g. by subsetting or WOFF2 encoding). Per WOFF2 spec section 5,
+      # encoders MUST set this bit. Chrome's OpenType Sanitizer (OTS)
+      # rejects WOFF2 files where it is not set.
+      FLAG_LOSSLESS_MODIFYING = 0x0800
+
       # Version as 16.16 fixed-point (stored as int32)
       int32 :version_raw
 

data/lib/fontisan/version.rb

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