fontisan 0.4.12 → 0.4.13

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
 

data/lib/fontisan/woff2/encoder_rules.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Woff2
+    # Applies WOFF2 spec "encoder MUST" rules to a table collection before
+    # the table directory is built and brotli compression is applied.
+    #
+    # Each spec-mandated transform lives here so the encoder stays a thin
+    # orchestrator and new rules are MECE/discoverable instead of sprinkled
+    # as inline conditionals across Woff2Encoder.
+    #
+    # Reference: W3C WOFF2 spec, section 5 ("Recommended table directory").
+    class EncoderRules
+      # Tables that MUST NOT appear in WOFF2 output.
+      #
+      # Per spec section 5: "The compliant WOFF2 encoder MUST remove the
+      # DSIG table from an input font data, prior to applying
+      # transformations and entropy coding steps." Chrome's OpenType
+      # Sanitizer (OTS) rejects WOFF2 files that still contain DSIG.
+      EXCLUDED_TABLES = %w[DSIG].freeze
+
+      # Tables that MUST be transformed (when present) per WOFF2 spec
+      # section 5.3: glyf and loca are paired — both are either
+      # transformed (version 0) or null-transformed (version 3) together.
+      # Browsers (Chrome OTS) only accept the transformed form.
+      TRANSFORMED_TABLES = %w[glyf loca].freeze
+
+      # Apply all WOFF2 encoder rules to `table_data` in place.
+      #
+      # @param table_data [Hash{String => String}] Map of tag → binary
+      #   table data. Mutated.
+      # @return [Hash{String => String}] The same hash, for chaining.
+      def self.apply!(table_data)
+        exclude_tables!(table_data)
+        mark_lossless_modifying!(table_data)
+        table_data
+      end
+
+      # Whether `tag` is dropped by WOFF2 spec rules.
+      def self.excluded?(tag)
+        EXCLUDED_TABLES.include?(tag)
+      end
+
+      # Drop spec-excluded tables from the collection.
+      def self.exclude_tables!(table_data)
+        EXCLUDED_TABLES.each { |tag| table_data.delete(tag) }
+      end
+
+      # Set head.flags bit 11 to indicate the font was losslessly modified.
+      #
+      # Per spec section 5: "The WOFF 2.0 encoders MUST also set bit 11 of
+      # the 'flags' field of the head table ... to indicate that a recreated
+      # font file was subjected to lossless modifying transform."
+      #
+      # Uses the model-driven Head BinData record so the bit is set via a
+      # named attribute on a typed object, not via raw byte slicing.
+      def self.mark_lossless_modifying!(table_data)
+        return unless table_data.key?("head")
+
+        head = Tables::Head.read(table_data["head"])
+        head.flags |= Tables::Head::FLAG_LOSSLESS_MODIFYING
+        table_data["head"] = head.to_binary_s
+      end
+    end
+  end
+end

data/lib/fontisan/woff2/glyf_loca_transform.rb

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Woff2
+    # Encodes glyf + loca into the WOFF2 transformed glyf table format per
+    # WOFF2 spec section 5.1.
+    #
+    # The loca table is reconstructed by the decoder (its data is omitted
+    # from the brotli-compressed stream). Its directory entry keeps
+    # origLength and sets transformLength = 0 per spec section 5.3.
+    #
+    # Output layout (spec section 5.1):
+    #   uint16 version              # always 0
+    #   uint16 optionFlags          # bit 0 = overlapSimpleBitmap present
+    #   uint16 numGlyphs
+    #   uint16 indexFormat          # loca format (0=short, 1=long)
+    #   uint32 × 7 stream sizes
+    #   nContourStream:   int16[numGlyphs]
+    #   nPointsStream:    255UInt16 per contour (point count, not endpoint)
+    #   flagStream:       uint8[numPoints] (triplet flags)
+    #   glyphStream:      triplet payloads + 255UInt16 instructionLength per glyph
+    #   compositeStream:  raw component bytes per composite glyph
+    #   bboxStream:       bboxBitmap + explicit bbox int16[4] entries
+    #   instructionStream: raw instruction bytes
+    #   overlapSimpleBitmap (optional)
+    class GlyfLocaTransform
+      # TrueType simple-glyph flag bits per OpenType spec.
+      FLAG_ON_CURVE = 0x01
+      FLAG_OVERLAP_SIMPLE = 0x40
+
+      # TrueType composite-glyph flag bits.
+      ARG_1_AND_2_ARE_WORDS = 0x0001
+      WE_HAVE_A_SCALE = 0x0008
+      MORE_COMPONENTS = 0x0020
+      WE_HAVE_AN_X_AND_Y_SCALE = 0x0040
+      WE_HAVE_A_TWO_BY_TWO = 0x0080
+      WE_HAVE_INSTRUCTIONS = 0x0100
+
+      # Simple glyph records start with int16 numberOfContours + 4 int16 bbox.
+      SIMPLE_HEADER_SIZE = 10
+
+      attr_reader :num_glyphs, :index_format
+
+      # @param glyf_data [String] raw glyf table bytes
+      # @param loca_data [String] raw loca table bytes
+      # @param num_glyphs [Integer] from maxp
+      # @param index_format [Integer] 0 (short) or 1 (long), from head
+      def initialize(glyf_data:, loca_data:, num_glyphs:, index_format:)
+        @glyf_data = glyf_data
+        @loca_data = loca_data
+        @num_glyphs = num_glyphs
+        @index_format = index_format
+      end
+
+      # Encode the glyf/loca transform, returning the transformed glyf bytes.
+      #
+      # @return [String] transformed glyf bytes per spec section 5.1
+      def transform
+        s = Streams.new(@num_glyphs)
+        offsets = parse_loca_offsets
+
+        num_glyphs.times do |glyph_id|
+          start_off = offsets[glyph_id]
+          end_off = offsets[glyph_id + 1]
+          glyph_bytes = @glyf_data[start_off...end_off]
+
+          if glyph_bytes.nil? || glyph_bytes.empty? || glyph_bytes.bytesize.zero?
+            s.n_contour << [0].pack("s>")
+            next
+          end
+
+          num_contours = read_int16(glyph_bytes, 0)
+          bbox = read_bbox(glyph_bytes, 2)
+
+          case num_contours
+          when 0
+            s.n_contour << [0].pack("s>")
+          when -1
+            encode_composite(s:, glyph_bytes:, bbox:, glyph_id:)
+          else
+            encode_simple(s:, glyph_bytes:, num_contours:, bbox:, glyph_id:)
+          end
+        end
+
+        assemble(s)
+      end
+
+      # Mutable container for the 7 streams + 2 bitmaps. Avoids passing 9
+      # parameters through every helper. Defined at top-level so the Struct
+      # class isn't hidden behind `private` (Ruby treats constants as public
+      # regardless, but RuboCop flags the modifier as useless).
+      Streams = Struct.new(:n_contour, :n_points, :flags, :glyph, :composite,
+                           :bbox_data, :instructions, :bbox_bitmap,
+                           :overlap_bitmap) do
+        def initialize(num_glyphs)
+          super(*Array.new(7) { String.new(encoding: Encoding::BINARY) },
+                Array.new(((num_glyphs + 31) >> 5) << 2, 0),
+                Array.new((num_glyphs + 7) >> 3, 0))
+        end
+
+        def has_overlap?
+          overlap_bitmap.any?(&:nonzero?)
+        end
+
+        # bboxStream on the wire = bboxBitmap || bboxStream (spec section 5.1).
+        def bbox_wire
+          bbox_bitmap.pack("C*") + bbox_data
+        end
+      end
+
+      private
+
+      def encode_simple(s:, glyph_bytes:, num_contours:, bbox:, glyph_id:)
+        s.n_contour << [num_contours].pack("s>")
+
+        io = StringIO.new(glyph_bytes)
+        io.pos = SIMPLE_HEADER_SIZE
+        end_pts = Array.new(num_contours) { io.read(2).unpack1("n") }
+        total_points = end_pts.last + 1
+
+        # 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)
+          prev_end = ep
+        end
+
+        inst_len = io.read(2).unpack1("n")
+        instructions = io.read(inst_len)
+
+        tt_flags = decode_truetype_flags(io, total_points)
+        xs = decode_coordinates(io, tt_flags, x_axis: true)
+        ys = decode_coordinates(io, tt_flags, x_axis: false)
+
+        # Re-encode each point as a WOFF2 triplet
+        prev_x = prev_y = 0
+        total_points.times do |i|
+          dx = xs[i] - prev_x
+          dy = ys[i] - prev_y
+          prev_x = xs[i]
+          prev_y = ys[i]
+          on_curve = (tt_flags[i] & FLAG_ON_CURVE).nonzero?
+          flag, payload = TripletCodec.encode(dx, dy, on_curve:)
+          s.flags << [flag].pack("C")
+          s.glyph << payload.pack("C*")
+        end
+
+        # Overlap bit lives on the first flag of each simple glyph
+        if (tt_flags.first & FLAG_OVERLAP_SIMPLE).nonzero?
+          s.overlap_bitmap[glyph_id >> 3] |= (0x80 >> (glyph_id & 7))
+        end
+
+        # glyphStream carries per-glyph instructionLength; bytes go to instructionStream
+        s.glyph << encode_255_uint16(instructions.bytesize)
+        s.instructions << instructions
+
+        # Spec: simple glyphs omit bbox when it matches calculated bounds.
+        calculated = calc_bounds(xs, ys)
+        return if calculated == bbox
+
+        set_bbox_bit(s, glyph_id)
+        s.bbox_data << bbox.pack("s>*")
+      end
+
+      def encode_composite(s:, glyph_bytes:, bbox:, glyph_id:)
+        s.n_contour << [-1].pack("s>")
+
+        io = StringIO.new(glyph_bytes)
+        io.pos = SIMPLE_HEADER_SIZE
+
+        components_end = nil
+        have_instructions = false
+        loop do
+          flags = io.read(2).unpack1("n")
+          io.read(2) # glyphIndex
+          io.read((flags & ARG_1_AND_2_ARE_WORDS).nonzero? ? 4 : 2)
+          io.read(component_transform_size(flags))
+          components_end = io.pos
+          have_instructions = (flags & WE_HAVE_INSTRUCTIONS).nonzero?
+          break if (flags & MORE_COMPONENTS).zero?
+        end
+
+        s.composite << glyph_bytes[SIMPLE_HEADER_SIZE...components_end]
+
+        if have_instructions
+          inst_len = io.read(2).unpack1("n")
+          instructions = io.read(inst_len)
+          s.glyph << encode_255_uint16(instructions.bytesize)
+          s.instructions << instructions
+        end
+
+        # Composite glyphs MUST have explicit bbox per spec section 5.1
+        set_bbox_bit(s, glyph_id)
+        s.bbox_data << bbox.pack("s>*")
+      end
+
+      def component_transform_size(flags)
+        if (flags & WE_HAVE_A_SCALE).nonzero? then 2
+        elsif (flags & WE_HAVE_AN_X_AND_Y_SCALE).nonzero? then 4
+        elsif (flags & WE_HAVE_A_TWO_BY_TWO).nonzero? then 8
+        else
+          0
+        end
+      end
+
+      def decode_truetype_flags(io, total_points)
+        flags = []
+        while flags.size < total_points
+          flag = io.read(1).unpack1("C")
+          flags << flag
+          if (flag & 0x08).nonzero? # REPEAT_FLAG
+            repeat = io.read(1).unpack1("C")
+            repeat.times { flags << flag }
+          end
+        end
+        flags
+      end
+
+      def decode_coordinates(io, flags, x_axis:)
+        short_flag = x_axis ? 0x02 : 0x04
+        same_flag = x_axis ? 0x10 : 0x20
+
+        coord = 0
+        coords = []
+        flags.each do |flag|
+          if (flag & short_flag).nonzero?
+            delta = io.read(1).unpack1("C")
+            delta = -delta if (flag & same_flag).zero?
+          elsif (flag & same_flag).nonzero?
+            delta = 0
+          else
+            delta = read_int16_io(io)
+          end
+          coord += delta
+          coords << coord
+        end
+        coords
+      end
+
+      def assemble(s)
+        bbox_bitmap_bytes = ((@num_glyphs + 31) >> 5) << 2
+        # Pad bbox_bitmap to required size (struct may have fewer bytes allocated)
+        bb = s.bbox_bitmap
+        if bb.size < bbox_bitmap_bytes
+          bb.concat(Array.new(bbox_bitmap_bytes - bb.size, 0))
+        end
+
+        out = String.new(encoding: Encoding::BINARY)
+        out << [0].pack("S>")                                  # version
+        out << [(s.has_overlap? ? 1 : 0)].pack("S>")           # optionFlags
+        out << [@num_glyphs].pack("S>")
+        out << [@index_format].pack("S>")
+        out << [s.n_contour.bytesize].pack("L>")
+        out << [s.n_points.bytesize].pack("L>")
+        out << [s.flags.bytesize].pack("L>")
+        out << [s.glyph.bytesize].pack("L>")
+        out << [s.composite.bytesize].pack("L>")
+        out << [s.bbox_wire.bytesize].pack("L>")
+        out << [s.instructions.bytesize].pack("L>")
+        out << s.n_contour
+        out << s.n_points
+        out << s.flags
+        out << s.glyph
+        out << s.composite
+        out << s.bbox_wire
+        out << s.instructions
+        out << s.overlap_bitmap.pack("C*") if s.has_overlap?
+        out
+      end
+
+      def parse_loca_offsets
+        if @index_format.zero?
+          @loca_data.unpack("n*").map { |v| v * 2 }
+        else
+          @loca_data.unpack("N*")
+        end
+      end
+
+      def set_bbox_bit(s, glyph_id)
+        s.bbox_bitmap[glyph_id >> 3] |= (0x80 >> (glyph_id & 7))
+      end
+
+      def read_int16(bytes, offset)
+        v = (bytes.getbyte(offset) << 8) | bytes.getbyte(offset + 1)
+        v > 0x7FFF ? v - 0x10000 : v
+      end
+
+      def read_int16_io(io)
+        v = io.read(2).unpack1("n")
+        v > 0x7FFF ? v - 0x10000 : v
+      end
+
+      def read_bbox(bytes, offset)
+        [
+          read_int16(bytes, offset),
+          read_int16(bytes, offset + 2),
+          read_int16(bytes, offset + 4),
+          read_int16(bytes, offset + 6),
+        ]
+      end
+
+      def calc_bounds(xs, ys)
+        return nil if xs.empty?
+
+        [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/triplet_codec.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Woff2
+    # Variable-length coordinate codec for the WOFF2 glyf transform.
+    #
+    # Per WOFF2 spec section 5.2, each (dx, dy, on_curve) point is encoded as
+    # one flag byte plus 1-4 payload bytes ("triplets"). The flag byte's high
+    # bit is the on-curve flag; the low 7 bits select one of 128 encoding
+    # variants. Variants are chosen by coordinate magnitude so small deltas
+    # cost 1-2 bytes and only very large deltas cost 4.
+    #
+    # Reference: WOFF2 spec section 5.2 (triplet encoding table).
+    module TripletCodec
+      ON_CURVE_BIT = 0x00
+      OFF_CURVE_BIT = 0x80
+
+      # Encode a single (dx, dy) delta with the given on-curve flag.
+      #
+      # @param dx [Integer] X delta (signed, -65535..65535)
+      # @param dy [Integer] Y delta (signed, -65535..65535)
+      # @param on_curve [Boolean] true if this is an on-curve point
+      # @return [Array(Integer, Array<Integer>)] flag byte and payload bytes
+      def self.encode(dx, dy, on_curve:)
+        on_curve_bit = on_curve ? ON_CURVE_BIT : OFF_CURVE_BIT
+        abs_x = dx.abs
+        abs_y = dy.abs
+        x_sign_bit = dx.negative? ? 0 : 1
+        y_sign_bit = dy.negative? ? 0 : 1
+        xy_sign_bits = x_sign_bit + (2 * y_sign_bit)
+
+        if dx.zero? && abs_y < 1280
+          encode_y_only(on_curve_bit, abs_y, y_sign_bit)
+        elsif dy.zero? && abs_x < 1280
+          encode_x_only(on_curve_bit, abs_x, x_sign_bit)
+        elsif abs_x < 65 && abs_y < 65
+          encode_nibble_pair(on_curve_bit, abs_x, abs_y, xy_sign_bits)
+        elsif abs_x < 769 && abs_y < 769
+          encode_byte_pair(on_curve_bit, abs_x, abs_y, xy_sign_bits)
+        elsif abs_x < 4096 && abs_y < 4096
+          encode_12_bit_pair(on_curve_bit, abs_x, abs_y, xy_sign_bits)
+        else
+          encode_16_bit_pair(on_curve_bit, abs_x, abs_y, xy_sign_bits)
+        end
+      end
+
+      # Decode one triplet given the flag byte and a cursor over payload bytes.
+      #
+      # @param flag [Integer] flag byte
+      # @param payload [Array<Integer>] payload bytes following the flag
+      # @return [Array(Integer, Integer, Boolean)] dx, dy, on_curve
+      def self.decode(flag, payload)
+        on_curve = (flag & OFF_CURVE_BIT).zero?
+        idx = flag & 0x7F
+
+        dx, dy = if idx < 10
+                   decode_y_only(idx, payload)
+                 elsif idx < 20
+                   decode_x_only(idx, payload)
+                 elsif idx < 84
+                   decode_nibble_pair(idx, payload)
+                 elsif idx < 120
+                   decode_byte_pair(idx, payload)
+                 elsif idx < 124
+                   decode_12_bit_pair(idx, payload)
+                 else
+                   decode_16_bit_pair(idx, payload)
+                 end
+        [dx, dy, on_curve]
+      end
+
+      class << self
+        private
+
+        # --- Encoders ---
+
+        # Variants 0-9: dy only (1 byte payload), dx=0, |dy| < 1280.
+        def encode_y_only(on_curve_bit, abs_y, y_sign_bit)
+          flag = on_curve_bit + ((abs_y & 0xF00) >> 7) + y_sign_bit
+          [flag, [abs_y & 0xFF]]
+        end
+
+        # Variants 10-19: dx only (1 byte payload), dy=0, |dx| < 1280.
+        def encode_x_only(on_curve_bit, abs_x, x_sign_bit)
+          flag = on_curve_bit + 10 + ((abs_x & 0xF00) >> 7) + x_sign_bit
+          [flag, [abs_x & 0xFF]]
+        end
+
+        # Variants 20-83: 4-bit X + 4-bit Y deltas (1 byte payload).
+        # Encodes (abs - 1) so the range 1..64 maps to nibble values 0..63.
+        def encode_nibble_pair(on_curve_bit, abs_x, abs_y, xy_sign_bits)
+          flag = on_curve_bit + 20 +
+            ((abs_x - 1) & 0x30) +
+            (((abs_y - 1) & 0x30) >> 2) +
+            xy_sign_bits
+          payload = (((abs_x - 1) & 0x0F) << 4) | ((abs_y - 1) & 0x0F)
+          [flag, [payload]]
+        end
+
+        # Variants 84-119: 8-bit X + 8-bit Y deltas (2 byte payload).
+        # Encodes (abs - 1) so the range 1..768 maps to byte values 0..767.
+        def encode_byte_pair(on_curve_bit, abs_x, abs_y, xy_sign_bits)
+          flag = on_curve_bit + 84 +
+            (12 * (((abs_x - 1) & 0x300) >> 8)) +
+            (((abs_y - 1) & 0x300) >> 6) +
+            xy_sign_bits
+          [flag, [(abs_x - 1) & 0xFF, (abs_y - 1) & 0xFF]]
+        end
+
+        # Variants 120-123: 12-bit X + 12-bit Y deltas (3 byte payload).
+        def encode_12_bit_pair(on_curve_bit, abs_x, abs_y, xy_sign_bits)
+          flag = on_curve_bit + 120 + xy_sign_bits
+          payload = [
+            (abs_x >> 4) & 0xFF,
+            ((abs_x & 0x0F) << 4) | ((abs_y >> 8) & 0x0F),
+            abs_y & 0xFF,
+          ]
+          [flag, payload]
+        end
+
+        # Variants 124-127: 16-bit X + 16-bit Y deltas (4 byte payload).
+        def encode_16_bit_pair(on_curve_bit, abs_x, abs_y, xy_sign_bits)
+          flag = on_curve_bit + 124 + xy_sign_bits
+          payload = [
+            (abs_x >> 8) & 0xFF, abs_x & 0xFF,
+            (abs_y >> 8) & 0xFF, abs_y & 0xFF
+          ]
+          [flag, payload]
+        end
+
+        # --- Decoders ---
+
+        def decode_y_only(idx, payload)
+          sign = (idx & 1).zero? ? -1 : 1
+          magnitude = ((idx & 0x0E) << 7) + payload.fetch(0)
+          [0, sign * magnitude]
+        end
+
+        def decode_x_only(idx, payload)
+          sign = (idx & 1).zero? ? -1 : 1
+          magnitude = (((idx - 10) & 0x0E) << 7) + payload.fetch(0)
+          [sign * magnitude, 0]
+        end
+
+        def decode_nibble_pair(idx, payload)
+          x_sign = ((idx - 20) & 0x01).zero? ? -1 : 1
+          y_sign = ((idx - 20) & 0x02).zero? ? -1 : 1
+          x_mag_base = ((idx - 20) & 0x30) +
+            ((payload.fetch(0) >> 4) & 0x0F) + 1
+          y_mag_base = (((idx - 20) & 0x0C) << 2) +
+            (payload.fetch(0) & 0x0F) + 1
+          [x_sign * x_mag_base, y_sign * y_mag_base]
+        end
+
+        def decode_byte_pair(idx, payload)
+          x_sign = (idx & 1).zero? ? -1 : 1
+          y_sign = ((idx >> 1) & 1).zero? ? -1 : 1
+          x_mag = 1 + (((idx - 84) / 12) << 8) + payload.fetch(0)
+          y_mag = 1 + ((((idx - 84) % 12) >> 2) << 8) + payload.fetch(1)
+          [x_sign * x_mag, y_sign * y_mag]
+        end
+
+        def decode_12_bit_pair(idx, payload)
+          x_sign = (idx & 1).zero? ? -1 : 1
+          y_sign = ((idx >> 1) & 1).zero? ? -1 : 1
+          x_mag = (payload.fetch(0) << 4) + (payload.fetch(1) >> 4)
+          y_mag = ((payload.fetch(1) & 0x0F) << 8) + payload.fetch(2)
+          [x_sign * x_mag, y_sign * y_mag]
+        end
+
+        def decode_16_bit_pair(idx, payload)
+          x_sign = (idx & 1).zero? ? -1 : 1
+          y_sign = ((idx >> 1) & 1).zero? ? -1 : 1
+          x_mag = (payload.fetch(0) << 8) + payload.fetch(1)
+          y_mag = (payload.fetch(2) << 8) + payload.fetch(3)
+          [x_sign * x_mag, y_sign * y_mag]
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/woff2.rb

@@ -5,9 +5,12 @@
 module Fontisan
   module Woff2
     autoload :Directory, "fontisan/woff2/directory"
+    autoload :EncoderRules, "fontisan/woff2/encoder_rules"
+    autoload :GlyfLocaTransform, "fontisan/woff2/glyf_loca_transform"
     autoload :GlyfTransformer, "fontisan/woff2/glyf_transformer"
     autoload :HmtxTransformer, "fontisan/woff2/hmtx_transformer"
     autoload :TableTransformer, "fontisan/woff2/table_transformer"
+    autoload :TripletCodec, "fontisan/woff2/triplet_codec"
     autoload :Woff2Header, "fontisan/woff2/header"
   end
 end