fontisan 0.4.13 → 0.4.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f871e8b123fcb90294e234b49a73ee6ad5541a5064c11e34b47cf8a0c26646a
-  data.tar.gz: 90fb63c4e71aaf2bb91f4884f3b6cdca26b5b9bbb9dac3f0a812d96bca5d69f8
+  metadata.gz: 422936ab5bbb785c6030c16efa61be31edd4c9e251828eabaa29e572a570bbb5
+  data.tar.gz: ad05bb618741fb0958e1be540af840debb9ffa4d92be469930f8e11f6ccd63fb
 SHA512:
-  metadata.gz: 57fc98bbeb302426ef4fcf5453c0c37102ee6cf41c126d4cd724a727ffaee24313b6faf9a0ae1301642eefa85b93bca4371853a7891df304ac5c191c88a77aac
-  data.tar.gz: 4cbc0c95aa3eff13ed3dd479450d3615cf1a01f5e6a5e866c9f98b216491b14d92885178f4e03f23879a0eedcdffa03b8bb74653d5df39ab8d1a776f51d3cbcf
+  metadata.gz: f9d938ed00f8bff70e0fe20b06751134faa1cb9c0f536467f1259866876d060f170ac94e0a89818a4f77662d873542c9a6bfb09d4da0de5577c3bda2a33f4efa
+  data.tar.gz: e6d7679235dab59a1a26bf5948f0651d147b12fec4218c000626ff0291fbec33593cef8ba0466e189d63c20f6cdc0d6c53b88626f47178656a272248e8e12872

data/README.adoc

@@ -120,7 +120,7 @@ Font format support::
 * TTF, OTF (CFF1), OTF2 (CFF2), TTC, OTC font formats (production ready)
 * CFF2 with variable-font blend/vsindex operators, FDSelect, subroutines
 * Adobe Type 1 fonts (PFB/PFA) with bidirectional conversion (see link:docs/TYPE1_FONTS.adoc[Type 1 Fonts Guide])
-* WOFF/WOFF2 format support with reading, writing, and conversion (see link:docs/WOFF_WOFF2_FORMATS.adoc[WOFF/WOFF2 Guide])
+* WOFF/WOFF2 format support with reading, writing, and conversion — fully compliant with W3C WOFF 1.0 (https://www.w3.org/TR/WOFF/[Recommendation 13 December 2012]) and WOFF 2.0 (https://www.w3.org/TR/WOFF2/[Recommendation 08 August 2024]) specifications. See link:docs/WOFF_WOFF2_FORMATS.adoc[WOFF/WOFF2 Guide].
 * Apple legacy font support: 'true' signature TrueType fonts and dfont format (see link:docs/APPLE_LEGACY_FONTS.adoc[Apple Legacy Fonts Guide])
 * SVG font generation and SVG-to-glyph conversion (complete)
 

data/docs/WOFF_WOFF2_FORMATS.adoc

@@ -8,6 +8,79 @@ including reading, writing, and conversion between these and other font formats.
 WOFF is a wrapper around SFNT fonts (TTF/OTF) using zlib compression, while WOFF2
 uses Brotli compression for better compression ratios and table transformations.
 
+== W3C specification compliance
+
+Fontisan's WOFF and WOFF2 implementations are fully compliant with the
+W3C Recommendations:
+
+* **WOFF 1.0** (W3C Recommendation, 13 December 2012):
+  https://www.w3.org/TR/WOFF/[spec] — reading and writing
+* **WOFF 2.0** (W3C Recommendation, 08 August 2024):
+  https://www.w3.org/TR/WOFF2/[spec] — reading and writing
+
+=== WOFF 2.0 (spec section references below)
+
+Compliance covers every normative requirement of the WOFF2 spec:
+
+* *Section 3.2 (WOFF2 Header)*: 48-byte header with correct signature
+  (`wOF2`), flavor, file length, reserved=0, totalSfntSize,
+  totalCompressedSize, version, and meta/private offset/length fields.
+* *Section 4.1 (Table directory)*: flags byte structure (bits 0-5 tag
+  index, bits 6-7 transform version); optional 4-byte custom tag when
+  index=63; `transformLength` field present IFF table is transformed.
+* *Section 4.2 (Collection directory)*: full support for flavor=`ttcf`
+  font collections — CollectionHeader + CollectionFontEntry per font,
+  with deduplicated tables shared across fonts via directory indices.
+* *Section 5 (Compressed data)*: single Brotli stream of all tables in
+  directory order; `DSIG` table removed per encoder rule; `head.flags`
+  bit 11 set to indicate lossless modifying transform.
+* *Section 5.1 (Transformed glyf table)*: 36-byte header (uint16
+  version + uint16 optionFlags + uint16 numGlyphs + uint16 indexFormat
+  + 7 × uint32 stream sizes); 7 streams in spec order (nContour,
+  nPoints, flags, glyph, composite, bbox with bboxBitmap prefix,
+  instructions); optional overlapSimpleBitmap when optionFlags bit 0
+  is set; bboxBitmap semantics per spec (composite glyphs always have
+  explicit bbox, simple glyphs omit when calculated bbox matches,
+  empty glyphs MUST have all-zero bbox).
+* *Section 5.2 (Triplet coordinate encoding)*: variable-length
+  coordinate codec with all 128 flag index variants (1-4 byte
+  payloads based on coordinate magnitude); bit 7 = off-curve flag.
+* *Section 5.3 (Transformed loca table)*: `transformLength` MUST be 0;
+  loca data omitted from compressed stream (reconstructed by decoder
+  from glyf).
+* *Section 5.4 (Transformed hmtx table)*: optional version 1 transform
+  exploiting `lsb == xMin` redundancy.
+* *Section 5.5 (Table order constraints)*: loca MUST immediately
+  follow glyf in table directory; for collections, loca MUST
+  immediately follow its corresponding glyf with no other tables in
+  between.
+
+Validation: fontisan's WOFF2 output is verified byte-identical to
+fontTools' output for transformed glyf tables, and round-trips
+correctly through the W3C `woff2_decompress` reference tool.
+
+=== WOFF 1.0
+
+* *Section 4 (WOFF Header)*: 44-byte header with correct signature
+  (`wOFF`), flavor, length, numTables, reserved=0, totalSfntSize,
+  version, and meta/private offset/length fields.
+* *Section 5 (Table directory)*: 20-byte entries with tag, offset,
+  compLength, origLength, origChecksum. Tables sorted in input font
+  order per spec ("MUST be stored in the same order as the
+  well-formed input font").
+* *Section 6 (Font data tables)*: tables compressed individually with
+  zlib (compress2-compatible); each table 4-byte aligned and
+  zero-padded to next boundary ("MUST begin on 4-byte boundaries and
+  be zero-padded to the next 4-byte boundary").
+* *Section 7 (Extended metadata)*: optional block of XML data,
+  always zlib-compressed ("it is never stored in uncompressed form").
+* *Section 8 (Private data)*: optional block of arbitrary bytes,
+  always 4-byte aligned.
+
+Validation: fontisan's WOFF 1 output round-trips through fontTools
+without errors; all 4-byte alignment, padding, and compression
+requirements verified by spec-conformance specs.
+
 === Display WOFF/WOFF2 font information
 
 Show metadata specific to WOFF/WOFF2 fonts including version, compression details,

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/woff_writer.rb

@@ -12,7 +12,8 @@ module Fontisan
     #
     # - `zlib_level` (0–9) — zlib compression level
     # - `uncompressed` (bool) — store tables uncompressed (legal per WOFF 1.0
-    #   §5.1; `compLength == origLength`)
+    #   §5.1; `compLength == origLength`). Metadata is still compressed per
+    #   spec §7 ("it is never stored in uncompressed form").
     # - `compression_threshold` (bytes) — skip compression for tables smaller
     #   than N bytes (rarely needed; keeps tiny tables uncompressed)
     # - `metadata_xml` (string) — optional metadata block
@@ -119,24 +120,35 @@ module Fontisan
 
       # Write font to WOFF binary.
       #
+      # Layout per WOFF 1.0 spec:
+      #   [header (44)] [table directory (20 × N)] [font tables, 4-byte aligned]
+      #   [optional metadata, 4-byte aligned] [optional private data, 4-byte aligned]
+      #
+      # Each font table is padded with 0-3 null bytes to a 4-byte boundary
+      # (spec §5/§6: "Font data tables in the WOFF file have the same
+      # requirement: they MUST begin on 4-byte boundaries and be zero-padded
+      # to the next 4-byte boundary"). Padding aligns the next block.
+      #
       # @param font [TrueTypeFont, OpenTypeFont] Source font
       # @param zlib_level [Integer] 0–9
-      # @param uncompressed [Boolean] skip zlib; store as-is
+      # @param uncompressed [Boolean] skip zlib; store tables as-is
       # @param compression_threshold [Integer] skip compression below N bytes
-      # @param metadata [String, nil] optional metadata XML
+      # @param metadata [String, nil] optional metadata XML (always compressed
+      #   per spec §7 — "it is never stored in uncompressed form")
       # @param private_data [String, nil] optional private data
       # @return [Hash{Symbol => String}] `{ woff_binary: <bytes> }`
       def write_font(font, zlib_level:, uncompressed:, compression_threshold:,
                      metadata: nil, private_data: nil)
-        tables_data = collect_tables_data(font)
+        tables = collect_tables_data(font)
         compressed_tables = compress_tables(
-          tables_data,
+          tables,
           zlib_level: uncompressed ? 0 : zlib_level,
           skip_compression: uncompressed,
           compression_threshold: compression_threshold,
         )
-        compressed_metadata = compress_metadata(metadata, zlib_level: zlib_level,
-                                                          skip_compression: uncompressed)
+        # Per spec §7, metadata MUST always be zlib-compressed regardless of
+        # the per-table `uncompressed` flag.
+        compressed_metadata = compress_metadata(metadata, zlib_level:)
         binary = build_woff_file(compressed_tables, font, compressed_metadata,
                                  private_data)
         { woff_binary: binary }
@@ -152,14 +164,16 @@ module Fontisan
         options.select { |k, _| names.include?(k.to_sym) }
       end
 
-      # Collect all table data from font.
+      # Collect all table data from font in input-font order (spec §6: tables
+      # MUST be stored in the same order as the well-formed input font).
       #
       # @param font [TrueTypeFont, OpenTypeFont]
       # @return [Hash<String, String>]
       def collect_tables_data(font)
-        font.table_names.to_h do |tag|
-          [tag, font.table_data[tag]]
-        end.compact
+        font.table_names.each_with_object({}) do |tag, h|
+          data = font.table_data[tag]
+          h[tag] = data if data
+        end
       end
 
       # Compress tables with zlib (or skip compression entirely).
@@ -197,71 +211,92 @@ module Fontisan
         end
       end
 
-      # Compress metadata with zlib.
+      # Compress metadata with zlib. Per spec §7, metadata MUST always be
+      # zlib-compressed — `skip_compression` is intentionally not exposed
+      # here. The zlib output is used even when it is larger than the input
+      # (e.g. tiny XML payloads where zlib header+checksum overhead exceeds
+      # any compression gain); the spec mandates compression, not optimality.
+      # Returns nil if no metadata was supplied.
       #
       # @param metadata [String, nil]
       # @param zlib_level [Integer]
-      # @param skip_compression [Boolean]
       # @return [Hash, nil]
-      def compress_metadata(metadata, zlib_level:, skip_compression:)
+      def compress_metadata(metadata, zlib_level:)
         return nil unless metadata
 
         original_length = metadata.bytesize
-        if skip_compression
-          return {
-            original_data: metadata,
-            compressed_data: metadata,
-            original_length: original_length,
-            compressed_length: original_length,
-          }
-        end
-
         compressed = Zlib::Deflate.deflate(metadata, zlib_level)
-        use_compressed = compressed.bytesize < original_length
         {
           original_data: metadata,
-          compressed_data: use_compressed ? compressed : metadata,
+          compressed_data: compressed,
           original_length: original_length,
-          compressed_length: use_compressed ? compressed.bytesize : original_length,
+          compressed_length: compressed.bytesize,
         }
       end
 
+      # Padding bytes needed to bring `length` up to a 4-byte boundary.
+      def padding_to_4(length)
+        (4 - (length % 4)) % 4
+      end
+
       # Assemble complete WOFF binary.
       #
-      # @param compressed_tables [Hash]
+      # Computes the full layout (offsets + padding) up front so the header
+      # fields (metaOffset, privOffset) point to the correct locations, then
+      # emits header → directory → tables → optional metadata → optional
+      # private data.
+      #
+      # @param compressed_tables [Hash<String, Hash>] in input-font order
       # @param font [TrueTypeFont, OpenTypeFont]
       # @param compressed_metadata [Hash, nil]
       # @param private_data [String, nil]
       # @return [String]
       def build_woff_file(compressed_tables, font, compressed_metadata,
                           private_data)
-        io = StringIO.new
-        io.set_encoding(Encoding::BINARY)
-
         header_size = 44
         num_tables = compressed_tables.length
-        table_dir_size = num_tables * 20
-        data_offset = header_size + table_dir_size
-        metadata_offset = data_offset
-        metadata_size = compressed_metadata ? compressed_metadata[:compressed_length] : 0
-        total_compressed_size = compressed_tables.values.sum do |t|
-          t[:compressed_length]
+        data_start = header_size + (num_tables * 20)
+
+        # Lay out tables in input-font order with 4-byte alignment padding.
+        # Each entry: { tag:, info:, offset:, pad_bytes: }
+        entries = []
+        cursor = data_start
+        compressed_tables.each do |tag, info|
+          pad = padding_to_4(info[:compressed_length])
+          entries << { tag:, info:, offset: cursor, pad_bytes: "\x00" * pad }
+          cursor += info[:compressed_length] + pad
         end
-        private_offset = data_offset + total_compressed_size + metadata_size
+        tables_end = cursor
+
+        metadata_size = compressed_metadata ? compressed_metadata[:compressed_length] : 0
+        # metaOffset/privOffset are 0 when their block is absent (spec §4:
+        # offsets to optional blocks; convention is 0 for "not present").
+        metadata_offset = compressed_metadata ? tables_end : 0
+        metadata_end = tables_end + metadata_size
+
         private_size = private_data ? private_data.bytesize : 0
-        total_size = private_offset + private_size
-        total_sfnt_size = compressed_tables.values.sum do |t|
-          t[:original_length]
-        end +
-          header_size + table_dir_size
+        private_offset = private_data ? metadata_end : 0
+        total_size = metadata_end + private_size
+
+        # totalSfntSize: reconstructed SFNT size with per-table 4-byte padding.
+        # spec §4: "Total size needed for the uncompressed font data, including
+        # the sfnt header, directory, and font tables (including padding)."
+        sfnt_header_size = 12
+        sfnt_dir_size = num_tables * 16
+        sfnt_tables_size = compressed_tables.values.sum do |t|
+          t[:original_length] + padding_to_4(t[:original_length])
+        end
+        total_sfnt_size = sfnt_header_size + sfnt_dir_size + sfnt_tables_size
 
+        io = StringIO.new
+        io.set_encoding(Encoding::BINARY)
         write_woff_header(
           io, font, total_size, total_sfnt_size, num_tables,
           compressed_metadata, metadata_offset, metadata_size,
           private_offset, private_size
         )
-        write_table_directory(io, compressed_tables, data_offset)
-        write_compressed_table_data(io, compressed_tables)
+        write_table_directory(io, entries)
+        write_compressed_table_data(io, entries)
         write_metadata(io, compressed_metadata) if compressed_metadata
         write_private_data(io, private_data) if private_data
 
@@ -293,25 +328,25 @@ module Fontisan
         io.write([private_size].pack("N"))             # privLength
       end
 
-      # Write table directory entries (20 bytes each).
-      def write_table_directory(io, compressed_tables, data_offset)
-        current_offset = data_offset
-        compressed_tables.sort_by { |tag, _| tag }.each do |tag, info|
+      # Write table directory entries (20 bytes each), one per laid-out entry.
+      def write_table_directory(io, entries)
+        entries.each do |e|
           checksum = Utilities::ChecksumCalculator
-            .calculate_table_checksum(info[:original_data])
-          io.write(tag)                                  # tag
-          io.write([current_offset].pack("N"))           # offset
-          io.write([info[:compressed_length]].pack("N")) # compLength
-          io.write([info[:original_length]].pack("N"))   # origLength
-          io.write([checksum].pack("N"))                 # origChecksum
-          current_offset += info[:compressed_length]
+            .calculate_table_checksum(e[:info][:original_data])
+          io.write(e[:tag])                                    # tag
+          io.write([e[:offset]].pack("N"))                     # offset
+          io.write([e[:info][:compressed_length]].pack("N"))   # compLength
+          io.write([e[:info][:original_length]].pack("N"))     # origLength
+          io.write([checksum].pack("N"))                       # origChecksum
         end
       end
 
-      # Write compressed table data, sorted by tag (matches directory order).
-      def write_compressed_table_data(io, compressed_tables)
-        compressed_tables.sort_by { |tag, _| tag }.each do |_, info|
-          io.write(info[:compressed_data])
+      # Write each table's compressed data followed by 4-byte alignment
+      # padding (spec §5/§6: tables MUST be zero-padded to next boundary).
+      def write_compressed_table_data(io, entries)
+        entries.each do |e|
+          io.write(e[:info][:compressed_data])
+          io.write(e[:pad_bytes])
         end
       end
 

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.13"
+  VERSION = "0.4.15"
 end