fontisan 0.4.14 → 0.4.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47e074b8c2bbdcfa377c95733f56fdd978dfa4d824dbae3e29f3bd75935dddd6
-  data.tar.gz: a1a348db0bd6dde039c0a43f62ac3ab43792cc7414e995a72c47798663a1cd59
+  metadata.gz: 1d27d25052549a912eab7392f8f0b34e7917fad9e9344d178b853bfe5a9fb476
+  data.tar.gz: 7fe03e99020f0a628efa4bac17236c455143345dbe4aef1dd1df5a8890cf00ad
 SHA512:
-  metadata.gz: e8917cc8c995f0ca2cbdc9e94ad5d5d629ab95d8809b7eb728d360f0743a2b26e5cfd059254497c5a1df10ddb3b53258ee703c441a106d4febd42b26ea3b6e08
-  data.tar.gz: d35a8138d7cdbc5389b619ed757863cc0d61e1d8d025655d0fb6736a21815f04d24802f24236fdffdc8d430192db79798f77f7b9343193e0c16035d2be8fc5eb
+  metadata.gz: 5ddb0c714d55d9f0e3b6b2ae02322f210d2392391d604368628cf6a789e2c1633645b08d4ee1edca6e05c0dc87e7c6e6ec550bc412bcc79fe751cc21f1e55f62
+  data.tar.gz: f8a646128fbadfd95df57bffc933a17095b3fb228603c941471198186df112bc517d836d09c567c1456b5aa8caed3aec4c14f8c561ba4cc19a4561bf75124940

data/lib/fontisan/commands/convert_command.rb

@@ -299,7 +299,7 @@ module Fontisan
       # Determine collection type from format
       #
       # @param format [Symbol] Target format
-      # @return [Symbol, nil] Collection type (:ttc, :otc, :dfont) or nil
+      # @return [Symbol, nil] Collection type (:ttc, :otc, :dfont, :woff2_collection) or nil
       def collection_type_from_format(format)
         case format
         when :ttc
@@ -308,6 +308,8 @@ module Fontisan
           :otc
         when :dfont
           :dfont
+        when :woff2
+          :woff2_collection
         else
           # Check output extension
           ext = File.extname(@output_path).downcase
@@ -318,6 +320,8 @@ module Fontisan
             :otc
           when ".dfont"
             :dfont
+          when ".woff2"
+            :woff2_collection
           end
         end
       end

data/lib/fontisan/config/conversion_matrix.yml

@@ -377,6 +377,42 @@ conversions:
       Unpacks dfont suitcase and repacks as OTC. If dfont contains TrueType
       fonts, they are converted to OpenType/CFF format.
 
+  # WOFF2 collection conversions (spec section 4.2)
+  - from: ttc
+    to: woff2_collection
+    strategy: collection_converter
+    description: "Convert TrueType Collection to WOFF2 collection"
+    status: implemented
+    notes: >
+      Unpacks TTC, encodes each font per WOFF2 spec, packs as a single
+      WOFF2 collection file (flavor='ttcf'). Tables shared across fonts
+      are deduplicated.
+
+  - from: otc
+    to: woff2_collection
+    strategy: collection_converter
+    description: "Convert OpenType Collection to WOFF2 collection"
+    status: implemented
+    notes: >
+      Unpacks OTC, encodes each font per WOFF2 spec, packs as a single
+      WOFF2 collection file (flavor='ttcf').
+
+  - from: woff2_collection
+    to: ttc
+    strategy: collection_converter
+    description: "Convert WOFF2 collection to TrueType Collection"
+    status: implemented
+    notes: >
+      Decodes WOFF2 collection, extracts each font, repacks as TTC.
+
+  - from: woff2_collection
+    to: otc
+    strategy: collection_converter
+    description: "Convert WOFF2 collection to OpenType Collection"
+    status: implemented
+    notes: >
+      Decodes WOFF2 collection, extracts each font, repacks as OTC.
+
 # Conversion compatibility matrix
 #
 # This section documents which source features are preserved in conversions.

data/lib/fontisan/converters/collection_converter.rb

@@ -121,9 +121,10 @@ module Fontisan
           raise ArgumentError, "Collection file not found: #{collection_path}"
         end
 
-        unless %i[ttc otc dfont].include?(target_type)
+        unless %i[ttc otc dfont woff2_collection].include?(target_type)
           raise ArgumentError,
-                "Invalid target type: #{target_type}. Must be :ttc, :otc, or :dfont"
+                "Invalid target type: #{target_type}. Must be :ttc, :otc, " \
+                ":dfont, or :woff2_collection"
         end
 
         unless options[:output]
@@ -145,6 +146,8 @@ module Fontisan
                   unpack_ttc_otc(collection_path)
                 when :dfont
                   unpack_dfont(collection_path)
+                when :woff2_collection
+                  unpack_woff2_collection(collection_path)
                 else
                   raise Error, "Unknown collection type: #{source_type}"
                 end
@@ -155,7 +158,7 @@ module Fontisan
       # Detect collection type from file
       #
       # @param path [String] Collection path
-      # @return [Symbol] Collection type (:ttc, :otc, or :dfont)
+      # @return [Symbol] Collection type (:ttc, :otc, :dfont, or :woff2_collection)
       def detect_collection_type(path)
         File.open(path, "rb") do |io|
           signature = io.read(4)
@@ -165,6 +168,12 @@ module Fontisan
             # TTC or OTC - check extension
             ext = File.extname(path).downcase
             ext == ".otc" ? :otc : :ttc
+          elsif signature == "wOF2"
+            # WOFF2 collection or single font — distinguish by flavor
+            io.read(8) # signature + flavor
+            io.rewind
+            flavor = File.binread(path, 4, 4)&.unpack1("N")
+            flavor == Woff2::CollectionDecoder::TTC_FLAVOR ? :woff2_collection : (raise Error, "Not a WOFF2 collection: #{path}")
           elsif Parsers::DfontParser.dfont?(io)
             :dfont
           else
@@ -207,6 +216,15 @@ module Fontisan
         fonts
       end
 
+      # Unpack fonts from WOFF2 collection (spec section 4.2).
+      #
+      # @param path [String] WOFF2 collection path
+      # @return [Array<Font>] Unpacked fonts
+      def unpack_woff2_collection(path)
+        collection = FontLoader.load_collection(path)
+        collection.extract_fonts
+      end
+
       # Convert fonts if outline format change needed
       #
       # @param fonts [Array<Font>] Source fonts
@@ -380,6 +398,8 @@ conv_options = nil)
           repack_ttc_otc(fonts, target_type, output_path, options)
         when :dfont
           repack_dfont(fonts, output_path, options)
+        when :woff2_collection
+          repack_woff2_collection(fonts, output_path, options)
         else
           raise Error, "Unknown target type: #{target_type}"
         end
@@ -415,6 +435,19 @@ conv_options = nil)
         builder.build_to_file(output_path)
       end
 
+      # Repack fonts into a WOFF2 collection (spec section 4.2).
+      #
+      # @param fonts [Array<Font>] Fonts
+      # @param output_path [String] Output path (.woff2)
+      # @param options [Hash] Options (looks for :brotli_quality)
+      # @return [void]
+      def repack_woff2_collection(fonts, output_path, options)
+        brotli_quality = options.fetch(:brotli_quality, 11)
+        encoder = Woff2::CollectionEncoder.new(brotli_quality:)
+        bytes = encoder.encode_fonts(fonts)
+        File.binwrite(output_path, bytes)
+      end
+
       # Build conversion result
       #
       # @param input [String] Input path

data/lib/fontisan/converters/woff2_encoder.rb

@@ -227,6 +227,12 @@ module Fontisan
       # are kept in `table_data` so its `origLength` is preserved; the
       # transformed bytes are passed to the entries builder separately.
       #
+      # glyf.origLength is computed by round-tripping the transformed glyf
+      # through the decoder — this guarantees the directory matches what
+      # any compliant decoder will produce, including padding and minor
+      # re-encoding differences (OFF section 5.3.3 allows multiple valid
+      # reconstructions of the same glyph data).
+      #
       # @return [Hash{Symbol => Object}, nil]
       def apply_glyf_loca_transform!(table_data, font)
         return nil unless font.respond_to?(:has_table?)
@@ -240,17 +246,32 @@ module Fontisan
         head = font.table("head")
         return nil unless maxp && head
 
+        index_format = head.index_to_loc_format
+
         transformed = Woff2::GlyfLocaTransform.new(
           glyf_data:,
           loca_data:,
           num_glyphs: maxp.num_glyphs,
-          index_format: head.index_to_loc_format,
+          index_format:,
         ).transform
 
-        loca_orig_length = loca_data.bytesize
+        # Round-trip through the decoder to get the exact reconstructed
+        # sizes the directory must advertise. fontTools re-compiles glyf
+        # during encoding, producing sizes that differ from the source by
+        # small amounts (encoding variations per OFF section 5.3.3). Using
+        # the source bytesize causes fontTools' decoder to reject the
+        # WOFF2 with "not enough 'glyf' table data".
+        reconstructed = Woff2::GlyfLocaReconstruct.new(
+          transformed_glyf: transformed,
+          num_glyphs: maxp.num_glyphs,
+          index_format:,
+        ).reconstruct
+
+        glyf_orig_length = reconstructed[:glyf].bytesize
+        loca_orig_length = reconstructed[:loca].bytesize
         table_data.delete("loca")
 
-        { transformed_glyf: transformed, loca_orig_length: }
+        { transformed_glyf: transformed, glyf_orig_length:, loca_orig_length: }
       end
 
       def get_table_data(font, tag)
@@ -277,7 +298,7 @@ module Fontisan
 
         table_data.keys.sort.each do |tag|
           if tag == "glyf" && glyf_transform
-            entries << build_glyf_entry(table_data["glyf"],
+            entries << build_glyf_entry(glyf_transform[:glyf_orig_length],
                                         glyf_transform[:transformed_glyf])
             entries << build_loca_entry(glyf_transform[:loca_orig_length])
             transformed_data["glyf"] = glyf_transform[:transformed_glyf]
@@ -314,13 +335,13 @@ module Fontisan
         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)
+      # Build the glyf directory entry. origLength is the reconstructed
+      # glyf size (what a decoder will produce); transformLength is the
+      # size of the WOFF2-transformed glyf stream per spec section 5.1.
+      def build_glyf_entry(glyf_orig_length, transformed_data)
         entry = Woff2::Directory::Entry.new
         entry.tag = "glyf"
-        entry.orig_length = orig_data.bytesize
+        entry.orig_length = glyf_orig_length
         entry.transform_length = transformed_data.bytesize
         entry.flags = entry.calculate_flags
         entry

data/lib/fontisan/font_loader.rb

@@ -45,6 +45,7 @@ module Fontisan
       ttc: TrueTypeCollection,
       otc: OpenTypeCollection,
       dfont: DfontCollection,
+      woff2_collection: Woff2Collection,
     }.freeze
     private_constant :COLLECTION_CLASSES
 
@@ -83,6 +84,8 @@ module Fontisan
                                                  lazy: resolved_lazy)
       when :ttc, :otc then load_from_collection(path, format, font_index,
                                                 mode: resolved_mode)
+      when :woff2_collection then load_from_collection(path, format, font_index,
+                                                       mode: resolved_mode)
       when :dfont then load_dfont(path, font_index: font_index,
                                         mode: resolved_mode)
       when :pfa, :pfb then Type1Font.from_file(path, mode: resolved_mode)
@@ -185,7 +188,7 @@ module Fontisan
                when Constants::SFNT_OTTO_MAGIC then :otf
                when Constants::SFNT_TRUETYPE_MAGIC, Constants::SFNT_TRUE_MAGIC then :ttf
                when Constants::WOFF_MAGIC then :woff
-               when Constants::WOFF2_MAGIC then :woff2
+               when Constants::WOFF2_MAGIC then scan_woff2(io)
                when Constants::DFONT_RESOURCE_HEADER
                  io.rewind
                  Parsers::DfontParser.dfont?(io) ? :dfont : nil
@@ -238,6 +241,18 @@ module Fontisan
       nil
     end
 
+    # Distinguish a WOFF2 collection (flavor='ttcf') from a single-font
+    # WOFF2. The 8-byte probe covers the WOFF2 signature + flavor field;
+    # spec section 3.2 requires flavor='ttcf' (0x74746366) for collections.
+    def self.scan_woff2(io)
+      io.rewind
+      io.read(4) # signature (already matched)
+      flavor = io.read(4)&.unpack1("N")
+      flavor == Woff2::CollectionDecoder::TTC_FLAVOR ? :woff2_collection : :woff2
+    rescue IOError
+      :woff2
+    end
+
     # Mode override from FONTISAN_MODE env var, or nil.
     def self.env_mode
       env_value = ENV["FONTISAN_MODE"]
@@ -287,6 +302,7 @@ module Fontisan
     private_class_method :detect,
                          :type1_format_from_header,
                          :scan_collection,
+                         :scan_woff2,
                          :env_mode,
                          :env_lazy,
                          :load_from_collection,

data/lib/fontisan/sfnt_builder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  # Builds an SFNT (TrueType/OpenType) binary from a flavor + per-tag table
+  # data. Used whenever WOFF2-derived table data needs to be reassembled
+  # into a parseable SFNT (single-font decoding, WOFF2 collection → font).
+  #
+  # Single source of truth for the SFNT byte layout: 12-byte offset table,
+  # 16-byte table directory entries, padded table data.
+  module SfntBuilder
+    # @param flavor [Integer] SFNT version (Constants::SFNT_VERSION_TRUETYPE
+    #   or Constants::SFNT_VERSION_OTTO)
+    # @param tables [Hash<String => String>] tag → table bytes
+    # @return [String] SFNT binary
+    def self.build(flavor:, tables:)
+      num_tables = tables.length
+      entry_selector = (Math.log(num_tables) / Math.log(2)).floor
+      search_range = (2**entry_selector) * 16
+      range_shift = (num_tables * 16) - search_range
+
+      out = String.new(encoding: Encoding::BINARY)
+      # Offset table (12 bytes)
+      out << [flavor].pack("N")
+      out << [num_tables].pack("n")
+      out << [search_range].pack("n")
+      out << [entry_selector].pack("n")
+      out << [range_shift].pack("n")
+
+      # Compute layout for table directory + table data with 4-byte padding
+      data_start = 12 + (num_tables * 16)
+      cursor = data_start
+      records = tables.map do |tag, data|
+        length = data.bytesize
+        checksum = Utilities::ChecksumCalculator.calculate_table_checksum(data)
+        padding = (4 - (length % 4)) % 4
+        record = { tag:, checksum:, offset: cursor, length:, data:, padding: }
+        cursor += length + padding
+        record
+      end
+
+      # Write all table directory entries first (16 bytes each, sorted
+      # alphabetically per SFNT convention for stable output), then all
+      # table data with 4-byte padding. The directory entries' offset
+      # fields were precomputed assuming this layout.
+      sorted = records.sort_by { |r| r[:tag] }
+      # rubocop:disable Style/CombinableLoops
+      # SFNT requires all directory entries before any table data
+      sorted.each do |r|
+        out << r[:tag].ljust(4, "\x00")
+        out << [r[:checksum]].pack("N")
+        out << [r[:offset]].pack("N")
+        out << [r[:length]].pack("N")
+      end
+
+      sorted.each do |r|
+        out << r[:data]
+        out << ("\x00" * r[:padding])
+      end
+      # rubocop:enable Style/CombinableLoops
+
+      out
+    end
+  end
+end

data/lib/fontisan/version.rb

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

data/lib/fontisan/woff2/collection_decoder.rb

@@ -0,0 +1,206 @@
+# 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 = UInt255.decode_at(@data, pos)
+        font_entries = Array.new(num_fonts) do
+          num_tables_f, pos2 = UInt255.decode_at(@data, pos)
+          pos = pos2
+          flavor = @data[pos, 4].unpack1("N")
+          pos += 4
+          indices = Array.new(num_tables_f) do
+            idx, pos2 = UInt255.decode_at(@data, 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
+    end
+  end
+end

data/lib/fontisan/woff2/collection_encoder.rb

@@ -238,7 +238,7 @@ module Fontisan
       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))
+        io.write(UInt255.encode(fonts.size))
 
         # One CollectionFontEntry per font
         fonts.each_with_index do |font, fi|
@@ -254,12 +254,12 @@ module Fontisan
           ordered << "loca" if has_placeholder
           ordered = ordered.sort
 
-          io.write(encode_255_uint16(ordered.size))
+          io.write(UInt255.encode(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))
+            io.write(UInt255.encode(index))
           end
         end
       end
@@ -271,18 +271,6 @@ module Fontisan
           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/directory.rb

@@ -235,48 +235,20 @@ module Fontisan
         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)
+      # Encode 255UInt16. Delegates to {UInt255} (single source of truth).
       #
       # @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
+        UInt255.encode(value)
       end
 
-      # Decode 255UInt16 from IO
+      # Decode 255UInt16 from IO. Delegates to {UInt255}.
       #
       # @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
+        UInt255.decode(io)
       end
     end
   end

data/lib/fontisan/woff2/encoder_rules.rb

@@ -52,12 +52,6 @@ module Fontisan
       # the 'flags' field of the head table ... to indicate that a recreated
       # font file was subjected to lossless modifying transform."
       #
-      # 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)
@@ -65,7 +59,6 @@ module Fontisan
 
         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

data/lib/fontisan/woff2/glyf_loca_reconstruct.rb

@@ -143,7 +143,7 @@ module Fontisan
         end_pts = []
         cumulative = -1
         num_contours.times do
-          pts_of_contour = read_255_uint16(streams[:n_points])
+          pts_of_contour = UInt255.decode(streams[:n_points])
           cumulative += pts_of_contour
           end_pts << cumulative
         end
@@ -169,7 +169,7 @@ module Fontisan
         end
 
         # Step 4-5: read instructionLength from glyphStream, bytes from instructionStream.
-        inst_len = read_255_uint16(streams[:glyph])
+        inst_len = UInt255.decode(streams[:glyph])
         instructions = streams[:instructions].read(inst_len)
 
         # Bbox: emit explicit bbox if bboxBitmap bit is set for this glyph,
@@ -209,7 +209,7 @@ module Fontisan
 
         instructions = String.new(encoding: Encoding::BINARY)
         if have_instructions
-          inst_len = read_255_uint16(streams[:glyph])
+          inst_len = UInt255.decode(streams[:glyph])
           instructions = streams[:instructions].read(inst_len)
         end
 
@@ -252,26 +252,6 @@ module Fontisan
         bytes ? bytes.bytes : Array.new(n_bytes, 0)
       end
 
-      def read_255_uint16(io)
-        return 0 if io.eof?
-
-        code = io.read(1)&.unpack1("C")
-        return 0 unless code
-
-        case code
-        when 0..252 then code
-        when 253
-          b = io.read(1)&.unpack1("C") || 0
-          253 + b
-        when 254
-          io.read(2)&.unpack1("n") || 0
-
-        when 255
-          v = io.read(2)&.unpack1("n") || 0
-          v + 506
-        end
-      end
-
       def read_uint16_io(io)
         io.read(2)&.unpack1("n") || 0
       end

data/lib/fontisan/woff2/glyf_loca_transform.rb

@@ -127,7 +127,7 @@ module Fontisan
         # nPoints stream: per-contour point counts (NOT endPtsOfContours).
         prev_end = -1
         end_pts.each do |ep|
-          s.n_points << encode_255_uint16(ep - prev_end)
+          s.n_points << UInt255.encode(ep - prev_end)
           prev_end = ep
         end
 
@@ -157,7 +157,7 @@ module Fontisan
         end
 
         # glyphStream carries per-glyph instructionLength; bytes go to instructionStream
-        s.glyph << encode_255_uint16(instructions.bytesize)
+        s.glyph << UInt255.encode(instructions.bytesize)
         s.instructions << instructions
 
         # Spec: simple glyphs omit bbox when it matches calculated bounds.
@@ -191,7 +191,7 @@ module Fontisan
         if have_instructions
           inst_len = io.read(2).unpack1("n")
           instructions = io.read(inst_len)
-          s.glyph << encode_255_uint16(instructions.bytesize)
+          s.glyph << UInt255.encode(instructions.bytesize)
           s.instructions << instructions
         end
 
@@ -255,10 +255,11 @@ module Fontisan
         out << [0].pack("S>")                                  # version
         out << [(s.has_overlap? ? 1 : 0)].pack("S>")           # optionFlags
         out << [@num_glyphs].pack("S>")
-        # Always emit indexFormat=0 per Chrome OTS requirement. WOFF2 spec
-        # section 5.1 allows the source's indexToLocFormat, but Chrome's
-        # OTS silently rejects any value other than 0.
-        out << [0].pack("S>")
+        # Emit the source's indexFormat. The earlier "always 0" override
+        # (commit 5f7e32d) was based on a misdiagnosis — Chrome's OTS
+        # accepts both 0 and 1, but short loca (0) can't address glyf
+        # offsets > 0x20000 bytes, so large fonts MUST use 1.
+        out << [@source_index_format].pack("S>")
         out << [s.n_contour.bytesize].pack("L>")
         out << [s.n_points.bytesize].pack("L>")
         out << [s.flags.bytesize].pack("L>")
@@ -313,18 +314,6 @@ module Fontisan
 
         [xs.min, ys.min, xs.max, ys.max]
       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/hmtx_transformer.rb

@@ -46,7 +46,7 @@ glyf_lsbs = nil)
         if (flags & HMTX_FLAG_EXPLICIT_ADVANCE_WIDTHS).zero?
           # Proportional encoding - read deltas
           # First advance width is explicit
-          first_advance = read_255_uint16(io)
+          first_advance = UInt255.decode(io)
           advance_widths << first_advance
 
           # Remaining are deltas from previous
@@ -57,7 +57,7 @@ glyf_lsbs = nil)
         else
           # Explicit advance widths in transformed format
           num_h_metrics.times do
-            advance_widths << read_255_uint16(io)
+            advance_widths << UInt255.decode(io)
           end
         end
 
@@ -88,31 +88,6 @@ glyf_lsbs = nil)
         build_hmtx_table(advance_widths, lsbs, num_h_metrics, num_glyphs)
       end
 
-      # Read variable-length 255UInt16 integer
-      #
-      # Format from WOFF2 spec:
-      # - value < 253: one byte
-      # - value == 253: 253 + next uint16
-      # - value == 254: 253 * 2 + next uint16
-      # - value == 255: 253 * 3 + next uint16
-      #
-      # @param io [StringIO] Input stream
-      # @return [Integer] Decoded value
-      def self.read_255_uint16(io)
-        code = read_uint8(io)
-
-        case code
-        when 255
-          759 + read_uint16(io)  # 253 * 3 + value
-        when 254
-          506 + read_uint16(io)  # 253 * 2 + value
-        when 253
-          253 + read_uint16(io)
-        else
-          code
-        end
-      end
-
       # Build standard hmtx table format
       #
       # Standard hmtx format:

data/lib/fontisan/woff2/table_transformer.rb

@@ -401,7 +401,7 @@ num_glyphs)
 
         # Write advance widths using proportional encoding
         # First advance width is explicit
-        data << encode_255_uint16(advance_widths[0])
+        data << UInt255.encode(advance_widths[0])
 
         # Remaining advance widths as deltas
         (1...num_h_metrics).each do |i|
@@ -473,7 +473,7 @@ num_glyphs)
             prev_pt = -1
             glyph[:end_pts].each do |pt|
               delta = pt - prev_pt - 1
-              n_points_stream << encode_255_uint16(delta)
+              n_points_stream << UInt255.encode(delta)
               prev_pt = pt
             end
 
@@ -488,7 +488,7 @@ num_glyphs)
             glyph[:bbox].each { |v| bbox_stream << [v].pack("n") }
 
             # Write instructions
-            instruction_stream << encode_255_uint16(glyph[:instructions].bytesize)
+            instruction_stream << UInt255.encode(glyph[:instructions].bytesize)
             instruction_stream << glyph[:instructions] if glyph[:instructions].bytesize.positive?
 
           when :composite
@@ -569,22 +569,6 @@ num_glyphs)
         end
       end
 
-      # Encode 255UInt16 value
-      #
-      # @param value [Integer] Value to encode
-      # @return [String] Encoded bytes
-      def encode_255_uint16(value)
-        if value < 253
-          [value].pack("C")
-        elsif value < 506
-          [253, value - 253].pack("CC")
-        elsif value < 65536
-          [254].pack("C") + [value].pack("n")
-        else
-          [255].pack("C") + [value - 506].pack("n")
-        end
-      end
-
       # Read signed 16-bit integer
       #
       # @param io [StringIO] Input stream

data/lib/fontisan/woff2/uint255.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Woff2
+    # 255UInt16 variable-length encoding per WOFF2 spec section 3.1.
+    #
+    # Single source of truth for encoding and decoding this data type. All
+    # other WOFF2 code MUST delegate to this module — the previous inline
+    # copies had the code-byte mapping inverted for values ≥ 253.
+    #
+    # Encoding table (per W3C spec pseudocode):
+    #
+    #   value range     | encoding              | bytes
+    #   ----------------|-----------------------|------
+    #   0 .. 252        | literal              | 1
+    #   253 .. 505      | code 255 + (v - 253) | 2
+    #   506 .. 761      | code 254 + (v - 506) | 2
+    #   762 .. 65535    | code 253 + uint16    | 3
+    #
+    # Decoding (inverse):
+    #
+    #   code byte | meaning
+    #   ----------|--------------------------------
+    #   0 .. 252  | literal value
+    #   253       | read uint16 → value
+    #   254       | read 1 byte → value + 506
+    #   255       | read 1 byte → value + 253
+    module UInt255
+      WORD_CODE = 253
+      ONE_MORE_BYTE_CODE1 = 255 # adds 253
+      ONE_MORE_BYTE_CODE2 = 254 # adds 506
+
+      MAX_VALUE = 65_535
+
+      # Encode a value (0..65535) into a 1-3 byte binary string.
+      #
+      # @param value [Integer]
+      # @return [String] binary-encoded bytes
+      # @raise [ArgumentError] if value is out of range
+      def self.encode(value)
+        case value
+        when 0..252
+          [value].pack("C")
+        when 253..505
+          [ONE_MORE_BYTE_CODE1, value - 253].pack("C*")
+        when 506..761
+          [ONE_MORE_BYTE_CODE2, value - 506].pack("C*")
+        when 762..MAX_VALUE
+          [WORD_CODE].pack("C") + [value].pack("n")
+        else
+          raise ArgumentError,
+                "255UInt16 requires 0 <= value <= #{MAX_VALUE}, got #{value}"
+        end
+      end
+
+      # Decode a 255UInt16 value from an IO stream. Reads 1-3 bytes.
+      #
+      # @param io [IO, StringIO] input stream positioned at the code byte
+      # @return [Integer, nil] decoded value, or nil if the stream is empty
+      def self.decode(io)
+        code = io.read(1)&.unpack1("C")
+        return nil unless code
+
+        case code
+        when 0..252
+          code
+        when WORD_CODE
+          io.read(2)&.unpack1("n")
+        when ONE_MORE_BYTE_CODE2
+          506 + (io.read(1)&.unpack1("C") || 0)
+        when ONE_MORE_BYTE_CODE1
+          253 + (io.read(1)&.unpack1("C") || 0)
+        end
+      end
+
+      # Decode from a binary String at a given position. Returns the value
+      # and the new cursor position. Used by callers that index into a
+      # flat String rather than wrapping it in a StringIO.
+      #
+      # @param data [String] binary data
+      # @param pos [Integer] byte offset of the code byte
+      # @return [Array(Integer, Integer)] [value, new_pos]
+      def self.decode_at(data, pos)
+        code = data.getbyte(pos)
+        pos += 1
+        case code
+        when 0..252
+          [code, pos]
+        when WORD_CODE
+          [data[pos, 2].unpack1("n"), pos + 2]
+        when ONE_MORE_BYTE_CODE2
+          [506 + data.getbyte(pos), pos + 1]
+        when ONE_MORE_BYTE_CODE1
+          [253 + data.getbyte(pos), pos + 1]
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/woff2.rb

@@ -4,6 +4,7 @@
 
 module Fontisan
   module Woff2
+    autoload :CollectionDecoder, "fontisan/woff2/collection_decoder"
     autoload :CollectionEncoder, "fontisan/woff2/collection_encoder"
     autoload :Directory, "fontisan/woff2/directory"
     autoload :EncoderRules, "fontisan/woff2/encoder_rules"
@@ -12,6 +13,7 @@ module Fontisan
     autoload :HmtxTransformer, "fontisan/woff2/hmtx_transformer"
     autoload :TableTransformer, "fontisan/woff2/table_transformer"
     autoload :TripletCodec, "fontisan/woff2/triplet_codec"
+    autoload :UInt255, "fontisan/woff2/uint255"
     autoload :Woff2Header, "fontisan/woff2/header"
   end
 end

data/lib/fontisan/woff2_collection.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  # WOFF2 font collection (spec section 4.2).
+  #
+  # Wraps a WOFF2 collection file (flavor='ttcf') and exposes the same
+  # interface as `TrueTypeCollection`/`OpenTypeCollection` so collection
+  # consumers don't need to know which container format they're holding.
+  #
+  # Unlike TTC/OTC (which subclass `BaseCollection` for BinData parsing),
+  # WOFF2 collections are decoded eagerly via `Woff2::CollectionDecoder`
+  # because the per-font tables require Brotli decompression +
+  # glyf/loca reconstruction before they can be returned.
+  class Woff2Collection
+    include Collection::SharedLogic
+
+    # @return [String] Source WOFF2 binary
+    attr_reader :data
+
+    # @param data [String] WOFF2 collection binary
+    def initialize(data)
+      @data = data.force_encoding(Encoding::BINARY)
+    end
+
+    # Load a WOFF2 collection from a file path.
+    #
+    # @param path [String]
+    # @return [Woff2Collection]
+    def self.from_file(path)
+      new(File.binread(path))
+    end
+
+    # Number of fonts in the collection.
+    #
+    # @return [Integer]
+    def num_fonts
+      decoded.length
+    end
+    alias font_count num_fonts
+
+    # Per-font synthetic offsets. WOFF2 collections don't have byte offsets
+    # like TTC (each font is reconstructed in memory); the index is the
+    # only identifier. Returned for compatibility with `BaseCollection`'s
+    # interface.
+    #
+    # @return [Array<Integer>] 0..num_fonts-1
+    def font_offsets
+      (0...num_fonts).to_a
+    end
+
+    # Extract every font in the collection.
+    #
+    # @param _io [IO, nil] Ignored — WOFF2 collections decode in memory.
+    # @return [Array<TrueTypeFont, OpenTypeFont>]
+    def extract_fonts(_io = nil)
+      decoded.map { |entry| build_font(entry) }
+    end
+
+    # Get a single font by index.
+    #
+    # @param index [Integer] 0-based font index
+    # @param _io [IO, nil] Ignored.
+    # @param _mode [Symbol] Ignored — full mode only (WOFF2 collections are
+    #   decoded eagerly).
+    # @return [TrueTypeFont, OpenTypeFont, nil] nil if index out of range
+    def font(index, _io = nil, _mode: LoadingModes::FULL)
+      return nil if index >= num_fonts
+
+      build_font(decoded[index])
+    end
+
+    # Whether this object represents a font collection. WOFF2 collections
+    # are always collections.
+    #
+    # @return [Boolean]
+    def collection? = true
+
+    # Collections have no single SFNT table directory.
+    #
+    # @return [Array<String>] empty
+    def table_names = []
+
+    # Validate format correctness.
+    #
+    # @return [Boolean]
+    def valid?
+      flavor = @data[4, 4].unpack1("N")
+      flavor == Woff2::CollectionDecoder::TTC_FLAVOR
+    rescue StandardError
+      false
+    end
+
+    # High-level pipeline format identifier. Owned by the collection class
+    # so the conversion pipeline can dispatch without case statements.
+    #
+    # @return [Symbol] :woff2_collection
+    def format = :woff2_collection
+
+    private
+
+    # Lazily decoded collection entries (one Hash per font).
+    def decoded
+      @decoded ||= Woff2::CollectionDecoder.new(@data).decode
+    end
+
+    # Build a TrueTypeFont or OpenTypeFont from a decoded font entry.
+    # Constructs an in-memory SFNT binary from the per-table data and
+    # loads it through the normal font reader path.
+    def build_font(entry)
+      sfnt = SfntBuilder.build(flavor: entry[:flavor], tables: entry[:tables])
+      sfnt_io = StringIO.new(sfnt)
+      font_class = truetype_flavor?(entry[:flavor]) ? TrueTypeFont : OpenTypeFont
+      font = font_class.read(sfnt_io)
+      font.initialize_storage
+      font.read_table_data(StringIO.new(sfnt))
+      font
+    end
+
+    def truetype_flavor?(flavor)
+      [Constants::SFNT_VERSION_TRUETYPE, 0x00010000].include?(flavor)
+    end
+  end
+end

data/lib/fontisan/woff2_font.rb

@@ -732,22 +732,6 @@ module Fontisan
       self.class.read_uint_base128_from_io(io)
     end
 
-    # Read 255UInt16 variable-length integer
-    def read_255_uint16(io)
-      code = io.read(1).unpack1("C")
-
-      case code
-      when 0..252
-        code
-      when 253
-        253 + io.read(1).unpack1("C")
-      when 254
-        io.read(2).unpack1("n")
-      when 255
-        io.read(2).unpack1("n") + 506
-      end
-    end
-
     # Calculate offset table fields
     def calculate_offset_table_fields(num_tables)
       entry_selector = (Math.log(num_tables) / Math.log(2)).floor

data/lib/fontisan.rb

@@ -116,6 +116,7 @@ module Fontisan
   autoload :OutlineExtractor, "fontisan/outline_extractor"
   autoload :SfntFont, "fontisan/sfnt_font"
   autoload :SfntTable, "fontisan/sfnt_table"
+  autoload :SfntBuilder, "fontisan/sfnt_builder"
   autoload :Stitcher, "fontisan/stitcher"
   autoload :StitcherCli, "fontisan/stitcher_cli"
   autoload :Tasks, "fontisan/tasks"
@@ -123,6 +124,7 @@ module Fontisan
   autoload :TrueTypeFont, "fontisan/true_type_font"
   autoload :TrueTypeFontExtensions, "fontisan/true_type_font_extensions"
   autoload :Type1Font, "fontisan/type1_font"
+  autoload :Woff2Collection, "fontisan/woff2_collection"
   autoload :Woff2Font, "fontisan/woff2_font"
   autoload :WoffFont, "fontisan/woff_font"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fontisan
 version: !ruby/object:Gem::Version
-  version: 0.4.14
+  version: 0.4.16
 platform: ruby
 authors:
 - Ribose Inc.
@@ -432,6 +432,7 @@ files:
 - lib/fontisan/pipeline/strategies/preserve_strategy.rb
 - lib/fontisan/pipeline/transformation_pipeline.rb
 - lib/fontisan/pipeline/variation_resolver.rb
+- lib/fontisan/sfnt_builder.rb
 - lib/fontisan/sfnt_font.rb
 - lib/fontisan/sfnt_table.rb
 - lib/fontisan/stitcher.rb
@@ -718,6 +719,7 @@ files:
 - lib/fontisan/version.rb
 - lib/fontisan/version.rb.orig
 - lib/fontisan/woff2.rb
+- lib/fontisan/woff2/collection_decoder.rb
 - lib/fontisan/woff2/collection_encoder.rb
 - lib/fontisan/woff2/directory.rb
 - lib/fontisan/woff2/encoder_rules.rb
@@ -727,6 +729,8 @@ files:
 - lib/fontisan/woff2/hmtx_transformer.rb
 - lib/fontisan/woff2/table_transformer.rb
 - lib/fontisan/woff2/triplet_codec.rb
+- lib/fontisan/woff2/uint255.rb
+- lib/fontisan/woff2_collection.rb
 - lib/fontisan/woff2_font.rb
 - lib/fontisan/woff_font.rb
 - scripts/compare_stack_aware.rb