fontisan 0.4.13 → 0.4.15

data/lib/fontisan/woff2/collection_decoder.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Woff2
+    # Decodes a WOFF2 font collection per spec section 4.2. This is the
+    # decoder counterpart of {Woff2::CollectionEncoder}.
+    #
+    # Layout parsed:
+    #   [WOFF2Header (48 bytes, flavor = 'ttcf')]
+    #   [TableDirectory]              # one entry per unique table
+    #   [CollectionDirectory]         # CollectionHeader + N CollectionFontEntry
+    #   [CompressedFontData]          # single brotli stream of all tables
+    #
+    # Each CollectionFontEntry references tables in the TableDirectory via
+    # indices. The decoder yields one reconstructed font per entry, with
+    # glyf/loca reconstruction per spec section 5.1/5.3 applied.
+    #
+    # Reference: W3C WOFF2 spec, section 4.2.
+    class CollectionDecoder
+      TTC_FLAVOR = 0x74746366 # 'ttcf'
+
+      # Parsed table directory entry: tag + raw bytes + transform state.
+      TableEntry = Struct.new(:tag, :raw_bytes, :orig_length, :transform_length,
+                              keyword_init: true)
+
+      # Parsed CollectionFontEntry: per-font table indices + flavor.
+      FontEntry = Struct.new(:flavor, :table_indices, keyword_init: true)
+
+      # @param data [String] WOFF2 collection binary
+      def initialize(data)
+        @data = data.dup.force_encoding(Encoding::BINARY)
+      end
+
+      # Decode the WOFF2 collection, returning one Hash per font containing
+      # the reconstructed table data ready to assemble into an SFNT.
+      #
+      # @return [Array<Hash{Symbol => Object}>] per-font:
+      #   {flavor:, tables: {tag ⇒ bytes}}
+      def decode
+        validate_signature!
+        validate_collection_flavor!
+
+        table_entries, post_dir_pos = read_table_directory
+        font_entries, post_coll_pos = read_collection_directory(post_dir_pos)
+        decompressed = decompress_table_data(post_coll_pos)
+
+        # Replace each table entry's raw_bytes by slicing from the
+        # decompressed stream at its cumulative offset.
+        cursor = 0
+        table_entries.each do |e|
+          len = e.transform_length || e.orig_length
+          e.raw_bytes = decompressed[cursor, len]
+          cursor += len
+        end
+
+        # For each font, gather its tables and reconstruct glyf/loca when
+        # the glyf was transformed.
+        font_entries.map do |fe|
+          font_tables = {}
+          fe.table_indices.each do |idx|
+            entry = table_entries.fetch(idx)
+            font_tables[entry.tag] = entry.raw_bytes
+          end
+          reconstruct_glyf_loca!(font_tables) if font_tables.key?("glyf")
+          { flavor: fe.flavor, tables: font_tables }
+        end
+      end
+
+      private
+
+      def validate_signature!
+        sig = @data[0, 4].unpack1("N")
+        return if sig == Woff2Header::SIGNATURE
+
+        raise InvalidFontError,
+              "Invalid WOFF2 signature: 0x#{sig.to_s(16)}"
+      end
+
+      def validate_collection_flavor!
+        flavor = @data[4, 4].unpack1("N")
+        return if flavor == TTC_FLAVOR
+
+        raise InvalidFontError,
+              "WOFF2 file is not a collection (flavor 0x#{flavor.to_s(16)}; " \
+              "expected 0x#{TTC_FLAVOR.to_s(16)} 'ttcf')"
+      end
+
+      def num_tables = @data[12, 2].unpack1("n")
+
+      def total_compressed_size = @data[20, 4].unpack1("N")
+
+      # Walk num_tables entries, returning the array of TableEntry and the
+      # byte position immediately after the table directory.
+      def read_table_directory
+        entries = []
+        pos = 48
+        num_tables.times do
+          entry, pos = read_one_directory_entry(pos)
+          entries << entry
+        end
+        [entries, pos]
+      end
+
+      def read_one_directory_entry(pos)
+        flags = @data.getbyte(pos)
+        pos += 1
+        tag_index = flags & 0x3F
+        transform_version = (flags >> 6) & 0x03
+        tag = if tag_index == 0x3F
+                t = @data[pos, 4]
+                pos += 4
+                t
+              else
+                Directory::KNOWN_TAGS.fetch(tag_index)
+              end
+        orig_length, pos = read_uint_base128(pos)
+        transform_length = nil
+        is_glyf_loca = ["glyf", "loca"].include?(tag)
+        is_transformed_hmtx = tag == "hmtx" && transform_version == 1
+        if (is_glyf_loca && transform_version.zero?) || is_transformed_hmtx
+          transform_length, pos = read_uint_base128(pos)
+        end
+        entry = TableEntry.new(tag:, raw_bytes: nil, orig_length:,
+                               transform_length:)
+        [entry, pos]
+      end
+
+      # Read CollectionHeader + N CollectionFontEntry records.
+      def read_collection_directory(pos)
+        version = @data[pos, 4].unpack1("N")
+        pos += 4
+        raise InvalidFontError, "Unsupported CollectionHeader version 0x#{version.to_s(16)}" unless version == 0x00010000
+
+        num_fonts, pos = read_255_uint16(pos)
+        font_entries = Array.new(num_fonts) do
+          num_tables_f, pos2 = read_255_uint16(pos)
+          pos = pos2
+          flavor = @data[pos, 4].unpack1("N")
+          pos += 4
+          indices = Array.new(num_tables_f) do
+            idx, pos2 = read_255_uint16(pos)
+            pos = pos2
+            idx
+          end
+          FontEntry.new(flavor:, table_indices: indices)
+        end
+        [font_entries, pos]
+      end
+
+      def decompress_table_data(start_pos)
+        compressed = @data[start_pos, total_compressed_size]
+        Utilities::BrotliWrapper.decompress(compressed)
+      end
+
+      # Reconstruct glyf + loca per spec section 5.1/5.3 when glyf is in
+      # transformed format. Replaces font_tables["glyf"] with reconstructed
+      # bytes and adds font_tables["loca"].
+      def reconstruct_glyf_loca!(font_tables)
+        glyf_bytes = font_tables["glyf"]
+        return unless glyf_bytes && glyf_bytes.bytesize >= 36
+
+        num_glyphs = parse_num_glyphs(font_tables)
+        index_format = parse_index_format(font_tables)
+        return unless num_glyphs && index_format
+
+        result = GlyfLocaReconstruct.new(
+          transformed_glyf: glyf_bytes,
+          num_glyphs:,
+          index_format:,
+        ).reconstruct
+        font_tables["glyf"] = result[:glyf]
+        font_tables["loca"] = result[:loca]
+      end
+
+      def parse_num_glyphs(font_tables)
+        maxp = font_tables["maxp"]
+        return nil unless maxp && maxp.bytesize >= 6
+
+        maxp[4, 2].unpack1("n")
+      end
+
+      def parse_index_format(font_tables)
+        head = font_tables["head"]
+        return nil unless head && head.bytesize >= 52
+
+        head[50, 2].unpack1("n")
+      end
+
+      def read_uint_base128(pos)
+        value = 0
+        5.times do
+          byte = @data.getbyte(pos)
+          pos += 1
+          if (byte & 0x80).zero?
+            value = (value << 7) | byte
+            return [value, pos]
+          end
+          value = (value << 7) | (byte & 0x7F)
+        end
+        raise InvalidFontError, "UIntBase128 sequence exceeds 5 bytes"
+      end
+
+      def read_255_uint16(pos)
+        code = @data.getbyte(pos)
+        pos += 1
+        case code
+        when 0..252 then [code, pos]
+        when 253
+          v = @data.getbyte(pos)
+          pos += 1
+          [253 + v, pos]
+        when 254
+          v = @data[pos, 2].unpack1("n")
+          pos += 2
+          [v, pos]
+        when 255
+          v = @data[pos, 2].unpack1("n")
+          pos += 2
+          [v + 506, pos]
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/woff2/collection_encoder.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "digest/sha2"
+
+module Fontisan
+  module Woff2
+    # Encodes a TTC/OTC font collection into WOFF2 collection format per
+    # spec section 4.2.
+    #
+    # Output layout:
+    #   [WOFF2Header (48 bytes, flavor = 'ttcf')]
+    #   [TableDirectory]              # one entry per unique table
+    #   [CollectionDirectory]         # CollectionHeader + N CollectionFontEntry
+    #   [CompressedFontData]          # single brotli stream of all tables
+    #
+    # Each font references tables via indices in its CollectionFontEntry.
+    # Identical tables across fonts share a single directory entry.
+    #
+    # Per spec section 5.5, glyf/loca pairs from the same font MUST be
+    # adjacent (loca immediately follows glyf) in the directory.
+    class CollectionEncoder
+      TTC_FLAVOR = 0x74746366 # 'ttcf'
+
+      # @param brotli_quality [Integer] 0-11
+      def initialize(brotli_quality: 11)
+        @brotli_quality = brotli_quality
+      end
+
+      # Encode an array of fonts as a WOFF2 collection.
+      #
+      # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Source fonts
+      # @return [String] WOFF2 collection binary
+      def encode_fonts(fonts)
+        raise ArgumentError, "fonts cannot be empty" if fonts.nil? || fonts.empty?
+
+        prepared = fonts.map.with_index { |font, i| prepare_font(font, i) }
+        _, font_to_ckeys = deduplicate(prepared)
+        layout = build_layout(prepared, font_to_ckeys)
+        compressed = compress_stream(layout)
+        assemble(fonts:, layout:, font_to_ckeys:, compressed:)
+      end
+
+      private
+
+      # Prepare a single font: collect tables, apply encoder rules, run
+      # glyf/loca transform. Returns a Hash:
+      #   {index:, tables: {tag ⇒ bytes}, loca_orig_length: (or nil)}
+      def prepare_font(font, index)
+        tables = {}
+        font.table_names.each do |tag|
+          data = font.table_data[tag]
+          next unless data && !data.empty?
+
+          tables[tag] = data
+        end
+
+        EncoderRules.apply!(tables)
+        loca_orig_length = apply_glyf_loca_transform!(tables, font)
+
+        { index:, tables:, loca_orig_length: }
+      end
+
+      # Apply the glyf/loca transform in place. Removes "loca" from
+      # `tables`. Returns the original loca length, or nil if not applied.
+      def apply_glyf_loca_transform!(tables, font)
+        return nil unless tables.key?("glyf") && tables.key?("loca")
+
+        maxp = font.table("maxp")
+        head = font.table("head")
+        return nil unless maxp && head
+
+        loca_orig_length = tables["loca"].bytesize
+        tables["glyf"] = GlyfLocaTransform.new(
+          glyf_data: tables["glyf"],
+          loca_data: tables["loca"],
+          num_glyphs: maxp.num_glyphs,
+          index_format: head.index_to_loc_format,
+        ).transform
+        tables.delete("loca")
+        loca_orig_length
+      end
+
+      # Deduplicate identical tables across fonts. Returns:
+      #   canonical: ckey → {tag, data}
+      #   font_to_ckeys: Array (per font) of {tag ⇒ ckey}
+      def deduplicate(prepared)
+        canonical = {}
+        font_to_ckeys = Array.new(prepared.size) { {} }
+        seen = {} # "tag:sha256" → ckey
+
+        prepared.each do |pf|
+          pf[:tables].each do |tag, data|
+            cache_key = "#{tag}:#{Digest::SHA256.digest(data)}"
+            if (existing = seen[cache_key])
+              font_to_ckeys[pf[:index]][tag] = existing
+            else
+              ckey = "#{tag}@#{pf[:index]}"
+              canonical[ckey] = { tag:, data: }
+              seen[cache_key] = ckey
+              font_to_ckeys[pf[:index]][tag] = ckey
+            end
+          end
+        end
+
+        [canonical, font_to_ckeys]
+      end
+
+      # Walk fonts in order; for each font, walk tags in spec-mandated
+      # order (glyf → loca placeholder → rest alphabetical). Each unique
+      # ckey appears once in the layout.
+      #
+      # Loca placeholders are keyed by the glyf ckey they pair with, so
+      # fonts that share a transformed glyf (via deduplication) also
+      # share the loca placeholder. Per spec section 5.5, loca MUST
+      # immediately follow glyf in the directory.
+      def build_layout(prepared, font_to_ckeys)
+        seen = {}
+        entries = []
+
+        prepared.each do |pf|
+          tags = pf[:tables].keys
+          ordered = order_tags_for_font(tags, has_loca: pf[:loca_orig_length])
+
+          ordered.each do |tag|
+            if tag == "loca_placeholder"
+              # Handled below as part of the glyf branch.
+              next
+            end
+
+            ckey = font_to_ckeys[pf[:index]][tag]
+            unless seen[ckey]
+              data = pf[:tables][tag]
+              seen[ckey] = entries.size
+              entries << {
+                ckey:, tag:,
+                data:,
+                orig_length: data.bytesize,
+                transform_length: (tag == "glyf" ? data.bytesize : nil)
+              }
+            end
+
+            # loca placeholder immediately after glyf. Tied to glyf's ckey
+            # so fonts that share a glyf also share its loca placeholder.
+            if tag == "glyf" && pf[:loca_orig_length]
+              placeholder_key = "loca_placeholder_for:#{ckey}"
+              unless seen[placeholder_key]
+                seen[placeholder_key] = entries.size
+                entries << {
+                  ckey: placeholder_key,
+                  tag: "loca",
+                  data: nil,
+                  orig_length: pf[:loca_orig_length],
+                  transform_length: 0,
+                }
+              end
+            end
+          end
+        end
+
+        entries
+      end
+
+      # Per-font tag order: glyf first, loca placeholder immediately after,
+      # rest alphabetical. Spec section 5.5.
+      def order_tags_for_font(tags, has_loca:)
+        return tags.sort unless has_loca
+
+        %w[glyf loca_placeholder] + (tags - ["glyf"]).sort
+      end
+
+      # Concatenate unique table data in directory order. Placeholder
+      # entries (loca after transform) contribute 0 bytes per spec 5.3.
+      def compress_stream(layout)
+        combined = String.new(encoding: Encoding::BINARY)
+        layout.each do |e|
+          combined << e[:data] if e[:data]
+        end
+        Utilities::BrotliWrapper.compress(combined, quality: @brotli_quality)
+      end
+
+      def assemble(fonts:, layout:, font_to_ckeys:, compressed:)
+        io = StringIO.new
+        io.set_encoding(Encoding::BINARY)
+
+        io.write("\x00" * 48) # reserve header
+        layout.each { |e| write_table_directory_entry(io, e) }
+
+        ckey_to_index = layout.each_with_index.to_h { |e, i| [e[:ckey], i] }
+        write_collection_directory(io, fonts, font_to_ckeys, ckey_to_index)
+
+        io.write(compressed)
+
+        # Pad to a 4-byte boundary. The W3C reference decoder validates that
+        # the file's `length` field matches the actual byte count, and many
+        # decoders expect a 4-byte-aligned file length for collections.
+        pad = (4 - (io.pos % 4)) % 4
+        io.write("\x00" * pad) if pad.positive?
+        total_size = io.size
+
+        io.pos = 0
+        write_header(io, num_tables: layout.size,
+                         total_compressed_size: compressed.bytesize, total_size:)
+        io.string
+      end
+
+      def write_header(io, num_tables:, total_compressed_size:, total_size:)
+        io.write([Woff2::Woff2Header::SIGNATURE].pack("N"))
+        io.write([TTC_FLAVOR].pack("N"))
+        io.write([total_size].pack("N"))
+        io.write([num_tables].pack("n"))
+        io.write([0].pack("n"))
+        io.write([0].pack("N"))                       # totalSfntSize (ref only)
+        io.write([total_compressed_size].pack("N"))
+        io.write([1].pack("n"))                       # majorVersion
+        io.write([0].pack("n"))                       # minorVersion
+        io.write([0].pack("N"))                       # metaOffset
+        io.write([0].pack("N"))                       # metaLength
+        io.write([0].pack("N"))                       # metaOrigLength
+        io.write([0].pack("N"))                       # privOffset
+        io.write([0].pack("N"))                       # privLength
+      end
+
+      def write_table_directory_entry(io, entry)
+        dir_entry = Directory::Entry.new
+        dir_entry.tag = entry[:tag]
+        dir_entry.orig_length = entry[:orig_length]
+        dir_entry.transform_length = entry[:transform_length]
+        flags = dir_entry.calculate_flags
+        io.write([flags].pack("C"))
+        io.write(entry[:tag].ljust(4, "\x00")) unless dir_entry.known_tag?
+        io.write(Directory.encode_uint_base128(entry[:orig_length]))
+        return unless dir_entry.transformed?
+
+        io.write(Directory.encode_uint_base128(entry[:transform_length] || 0))
+      end
+
+      def write_collection_directory(io, fonts, font_to_ckeys, ckey_to_index)
+        # CollectionHeader
+        io.write([0x00010000].pack("N")) # version 1.0
+        io.write(encode_255_uint16(fonts.size))
+
+        # One CollectionFontEntry per font
+        fonts.each_with_index do |font, fi|
+          font_keys = font_to_ckeys[fi]
+          glyf_ckey = font_keys["glyf"]
+          placeholder_key = glyf_ckey && "loca_placeholder_for:#{glyf_ckey}"
+          has_placeholder = ckey_to_index.key?(placeholder_key)
+          # CollectionFontEntry index list is in font's natural alphabetical
+          # order (including "loca" if a placeholder exists). The glyf/loca
+          # adjacency constraint applies to the table directory, not the
+          # entry index list per spec section 5.5.
+          ordered = font_keys.keys
+          ordered << "loca" if has_placeholder
+          ordered = ordered.sort
+
+          io.write(encode_255_uint16(ordered.size))
+          io.write([font_flavor(font)].pack("N"))
+          ordered.each do |tag|
+            ckey = font_keys[tag] || placeholder_key
+            index = ckey_to_index.fetch(ckey)
+            io.write(encode_255_uint16(index))
+          end
+        end
+      end
+
+      def font_flavor(font)
+        if font.has_table?("CFF ") || font.has_table?("CFF2")
+          Constants::SFNT_VERSION_OTTO
+        else
+          Constants::SFNT_VERSION_TRUETYPE
+        end
+      end
+
+      def encode_255_uint16(value)
+        if value < 253
+          [value].pack("C")
+        elsif value < 506
+          [253, value - 253].pack("CC")
+        elsif value < 65_536
+          [254].pack("C") + [value].pack("n")
+        else
+          [255].pack("C") + [value - 506].pack("n")
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/woff2/encoder_rules.rb

@@ -52,13 +52,20 @@ module Fontisan
       # the 'flags' field of the head table ... to indicate that a recreated
       # font file was subjected to lossless modifying transform."
       #
-      # Uses the model-driven Head BinData record so the bit is set via a
+      # Also forces head.indexToLocFormat=0 when the glyf/loca tables are
+      # transformed, because Chrome's OTS only accepts WOFF2 glyf
+      # indexFormat=0 (see GlyfLocaTransform). For the reconstructed font
+      # to be self-consistent, head.indexToLocFormat must match the loca
+      # format that the decoder will produce (always short, format=0).
+      #
+      # Uses the model-driven Head BinData record so the bits are set via a
       # named attribute on a typed object, not via raw byte slicing.
       def self.mark_lossless_modifying!(table_data)
         return unless table_data.key?("head")
 
         head = Tables::Head.read(table_data["head"])
         head.flags |= Tables::Head::FLAG_LOSSLESS_MODIFYING
+        head.index_to_loc_format = 0
         table_data["head"] = head.to_binary_s
       end
     end