fontisan 0.4.12 → 0.4.14

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

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

data/lib/fontisan/tables/head.rb

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

data/lib/fontisan/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fontisan
-  VERSION = "0.4.12"
+  VERSION = "0.4.14"
 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/directory.rb

@@ -46,15 +46,22 @@ module Fontisan
         "trak", "Zapf", "Silf", "Glat", "Gloc", "Feat", "Sill"
       ].freeze
 
-      # Transformation versions
-      # According to WOFF2 spec:
-      # - glyf/loca: version 0 or 3 WITH transformLength = transformed
-      # - glyf/loca: version 1 or 2 WITHOUT transformLength = not transformed
-      # - hmtx: version 1 WITH transformLength = transformed
-      # - hmtx: version 0, 2, or 3 WITHOUT transformLength = not transformed
-      TRANSFORM_NONE = 3           # Use version 3 when not transformed (works for all tables)
-      TRANSFORM_GLYF_LOCA = 0      # glyf/loca use version 0 when transformed
-      TRANSFORM_HMTX = 1           # hmtx uses version 1 when transformed
+      # Transformation versions per WOFF2 spec section 5.1, 5.3, 5.4.
+      #
+      # glyf/loca:
+      #   - version 0: transformed format (spec section 5.1 / 5.3)
+      #   - version 3: null transform — original bytes passed to brotli as-is
+      #     (Chrome's OTS does not accept version 3 for glyf/loca; encoders
+      #     that want to interoperate with browsers MUST use version 0).
+      # hmtx:
+      #   - version 0: null transform (default)
+      #   - version 1: transformed format (spec section 5.4)
+      # All other tables use version 0 for the null transform.
+      TRANSFORM_NULL = 3              # glyf/loca null transform
+      TRANSFORM_NONE = TRANSFORM_NULL # deprecated alias kept for older callers
+      TRANSFORM_GLYF_LOCA = 0         # glyf/loca transformed format
+      TRANSFORM_HMTX = 1              # hmtx transformed format
+      TRANSFORM_HMTX_NULL = 0         # hmtx null transform
 
       # Custom tag indicator
       CUSTOM_TAG_INDEX = 0x3F
@@ -92,11 +99,18 @@ module Fontisan
           KNOWN_TAGS.include?(tag)
         end
 
-        # Check if table is transformed
+        # Whether this entry will be serialized with a transformLength field.
+        #
+        # Per WOFF2 spec section 4.1, transformLength is encoded when the
+        # table is in a transformed format. For loca the value is always 0
+        # (spec section 5.3), so we cannot use `.positive?` to detect the
+        # transformed state — the encoder explicitly sets `transform_length`
+        # (even to 0) when emitting a transformed entry, and leaves it nil
+        # otherwise.
         #
-        # @return [Boolean] True if transformed
+        # @return [Boolean] True if a transformLength field should be written
         def transformed?
-          !transform_length.nil? && transform_length.positive?
+          !transform_length.nil?
         end
 
         # Get transformation version from flags
@@ -113,39 +127,22 @@ module Fontisan
           flags & 0x3F
         end
 
-        # Determine transformation version for this table
+        # Determine the transform version to encode in the flags byte.
         #
-        # Returns the appropriate version based on:
-        # 1. Whether table has transform_length set (is transformed)
-        # 2. Which table it is (glyf/loca vs hmtx vs other)
+        # Per WOFF2 spec section 5.1, glyf/loca use version 0 for the
+        # transformed format and version 3 for the null transform; hmtx
+        # uses version 1 for transformed and version 0 for null. The
+        # encoder sets `transform_length` (or leaves it nil) to indicate
+        # which case applies — see `transformed?`.
         #
         # @return [Integer] Transform version (0-3)
         def determine_transform_version
-          if transformed?
-            # Table IS transformed - use appropriate transform version
-            case tag
-            when "glyf", "loca"
-              TRANSFORM_GLYF_LOCA  # Version 0 for transformed glyf/loca
-            when "hmtx"
-              TRANSFORM_HMTX       # Version 1 for transformed hmtx
-            else
-              TRANSFORM_NONE       # Shouldn't happen, but use safe default
-            end
+          if ["glyf", "loca"].include?(tag)
+            transformed? ? TRANSFORM_GLYF_LOCA : TRANSFORM_NULL
+          elsif tag == "hmtx"
+            transformed? ? TRANSFORM_HMTX : TRANSFORM_HMTX_NULL
           else
-            # Table is NOT transformed - use version that indicates no transformation
-            case tag
-            when "glyf", "loca"
-              # For glyf/loca, version 0 means transformed
-              # so use version 3 to indicate NOT transformed
-              TRANSFORM_NONE # Version 3
-            when "hmtx"
-              # For hmtx, version 1 means transformed
-              # so use version 0 to indicate NOT transformed
-              0
-            else
-              # All other tables use version 0 (no transformation)
-              0
-            end
+            0
           end
         end