fontisan 0.2.5 → 0.2.7

data/lib/fontisan/base_collection.rb

@@ -2,6 +2,7 @@
 
 require "bindata"
 require_relative "constants"
+require_relative "collection/shared_logic"
 
 module Fontisan
   # Abstract base class for font collections (TTC/OTC)
@@ -29,6 +30,8 @@ module Fontisan
   #     end
   #   end
   class BaseCollection < BinData::Record
+    include Collection::SharedLogic
+
     endian :big
 
     string :tag, length: 4, assert: "ttcf"
@@ -251,8 +254,6 @@ module Fontisan
     # @param io [IO] Open file handle
     # @return [TableSharingInfo] Sharing statistics
     def calculate_table_sharing(io)
-      require_relative "models/table_sharing_info"
-
       font_class = self.class.font_class
 
       # Extract all fonts
@@ -260,37 +261,8 @@ module Fontisan
         font_class.from_collection(io, offset)
       end
 
-      # Build table hash map (checksum -> size)
-      table_map = {}
-      total_table_size = 0
-
-      fonts.each do |font|
-        font.tables.each do |entry|
-          key = entry.checksum
-          size = entry.table_length
-          table_map[key] ||= size
-          total_table_size += size
-        end
-      end
-
-      # Count unique vs shared
-      unique_tables = table_map.size
-      total_tables = fonts.sum { |f| f.tables.length }
-      shared_tables = total_tables - unique_tables
-
-      # Calculate space saved
-      unique_size = table_map.values.sum
-      space_saved = total_table_size - unique_size
-
-      # Calculate sharing percentage
-      sharing_pct = total_tables.positive? ? (shared_tables.to_f / total_tables * 100).round(2) : 0.0
-
-      Models::TableSharingInfo.new(
-        shared_tables: shared_tables,
-        unique_tables: unique_tables,
-        sharing_percentage: sharing_pct,
-        space_saved_bytes: space_saved,
-      )
+      # Use shared logic for calculation
+      calculate_table_sharing_for_fonts(fonts)
     end
   end
 end

data/lib/fontisan/cli.rb

@@ -220,6 +220,8 @@ module Fontisan
                          desc: "Skip output validation"
     option :preserve_hints, type: :boolean, default: false,
                             desc: "Preserve rendering hints during conversion (TTF→OTF preservations may be limited)"
+    option :target_format, type: :string, default: "preserve",
+                           desc: "Target outline format for collections: preserve (default), ttf, or otf"
     option :wght, type: :numeric,
                   desc: "Weight axis value (alternative to --coordinates)"
     option :wdth, type: :numeric,
@@ -236,6 +238,12 @@ module Fontisan
     # - TTF ↔ OTF: Outline format conversion
     # - WOFF/WOFF2: Web font packaging
     # - Variable fonts: Automatic variation preservation or instance generation
+    # - Collections (TTC/OTC/dfont): Preserve mixed TTF+OTF by default, or standardize with --target-format
+    #
+    # Collection Format Support:
+    # TTC, OTC, and dfont all support mixed TrueType and OpenType fonts. By default, original font formats
+    # are preserved during collection conversion (--target-format preserve). Use --target-format ttf to
+    # convert all fonts to TrueType, or --target-format otf to convert all to OpenType/CFF.
     #
     # Variable Font Operations:
     # The pipeline automatically detects whether variation data can be preserved based on
@@ -253,6 +261,15 @@ module Fontisan
     # @example Convert TTF to OTF
     #   fontisan convert font.ttf --to otf --output font.otf
     #
+    # @example Convert TTC to OTC (preserves mixed formats by default)
+    #   fontisan convert family.ttc --to otc --output family.otc
+    #
+    # @example Convert TTC to OTC with all fonts as TrueType
+    #   fontisan convert family.ttc --to otc --output family.otc --target-format ttf
+    #
+    # @example Convert TTC to OTC with all fonts as OpenType/CFF
+    #   fontisan convert family.ttc --to otc --output family.otc --target-format otf
+    #
     # @example Generate bold instance at specific coordinates
     #   fontisan convert variable.ttf --to ttf --output bold.ttf --coordinates "wght=700,wdth=100"
     #
@@ -493,7 +510,7 @@ module Fontisan
                     desc: "Output collection file path",
                     aliases: "-o"
     option :format, type: :string, default: "ttc",
-                    desc: "Collection format (ttc, otc)",
+                    desc: "Collection format (ttc, otc, dfont)",
                     aliases: "-f"
     option :optimize, type: :boolean, default: true,
                       desc: "Enable table sharing optimization",
@@ -501,10 +518,10 @@ module Fontisan
     option :analyze, type: :boolean, default: false,
                      desc: "Show analysis report before building",
                      aliases: "--analyze"
-    # Create a TTC (TrueType Collection) or OTC (OpenType Collection) from multiple font files.
+    # Create a TTC (TrueType Collection), OTC (OpenType Collection), or dfont (Apple Data Fork Font) from multiple font files.
     #
     # This command combines multiple fonts into a single collection file with
-    # shared table deduplication to save space. It supports both TTC and OTC formats.
+    # shared table deduplication to save space. It supports TTC, OTC, and dfont formats.
     #
     # @param font_files [Array<String>] Paths to input font files (minimum 2 required)
     #
@@ -514,6 +531,9 @@ module Fontisan
     # @example Pack into OTC with analysis
     #   fontisan pack Regular.otf Bold.otf Italic.otf --output family.otc --analyze
     #
+    # @example Pack into dfont (Apple suitcase)
+    #   fontisan pack font1.ttf font2.otf --output family.dfont --format dfont
+    #
     # @example Pack without optimization
     #   fontisan pack font1.ttf font2.ttf --output collection.ttc --no-optimize
     def pack(*font_files)
@@ -522,13 +542,13 @@ module Fontisan
 
       unless options[:quiet]
         puts "Collection created successfully:"
-        puts "  Output: #{result[:output]}"
+        puts "  Output: #{result[:output_path] || result[:output]}"
         puts "  Format: #{result[:format].upcase}"
         puts "  Fonts: #{result[:num_fonts]}"
-        puts "  Size: #{format_size(result[:output_size])}"
-        if result[:space_savings].positive?
+        puts "  Size: #{format_size(result[:output_size] || result[:total_size])}"
+        if result[:space_savings] && result[:space_savings].positive?
           puts "  Space saved: #{format_size(result[:space_savings])}"
-          puts "  Sharing: #{result[:sharing_percentage]}%"
+          puts "  Sharing: #{result[:statistics][:sharing_percentage]}%"
         end
       end
     rescue Errno::ENOENT, Error => e

data/lib/fontisan/collection/dfont_builder.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require_relative "../font_writer"
+require_relative "../error"
+require_relative "../validation/collection_validator"
+
+module Fontisan
+  module Collection
+    # DfontBuilder creates Apple dfont (Data Fork Font) resource fork structures
+    #
+    # Main responsibility: Build complete dfont binary from multiple fonts
+    # by creating a resource fork structure containing 'sfnt' resources.
+    #
+    # dfont is an Apple-specific format that stores Mac font suitcase resources
+    # in the data fork instead of the resource fork. It can contain multiple fonts.
+    #
+    # @example Build dfont from multiple fonts
+    #   builder = DfontBuilder.new([font1, font2, font3])
+    #   binary = builder.build
+    #
+    # @example Write directly to file
+    #   builder = DfontBuilder.new([font1, font2])
+    #   builder.build_to_file("family.dfont")
+    class DfontBuilder
+      # Source fonts
+      # @return [Array<TrueTypeFont, OpenTypeFont>]
+      attr_reader :fonts
+
+      # Build result (populated after build)
+      # @return [Hash, nil]
+      attr_reader :result
+
+      # Constants for resource reference packing
+      NO_NAME_OFFSET = [-1].freeze
+      ZERO_ATTRIBUTES = [0].freeze
+      ZERO_RESERVED = [0].freeze
+
+      # Initialize builder with fonts
+      #
+      # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Fonts to pack into dfont
+      # @param options [Hash] Builder options
+      # @raise [ArgumentError] if fonts array is invalid
+      def initialize(fonts, options = {})
+        if fonts.nil? || fonts.empty?
+          raise ArgumentError, "fonts cannot be nil or empty"
+        end
+        raise ArgumentError, "fonts must be an array" unless fonts.is_a?(Array)
+
+        unless fonts.all? { |f| f.respond_to?(:table_data) }
+          raise ArgumentError, "all fonts must respond to table_data"
+        end
+
+        @fonts = fonts
+        @options = options
+        @result = nil
+
+        validate_fonts!
+      end
+
+      # Build dfont and return binary
+      #
+      # Executes the complete dfont creation process:
+      # 1. Serialize each font to SFNT binary
+      # 2. Build resource data section
+      # 3. Calculate resource map size
+      # 4. Build resource map
+      # 5. Build resource fork header
+      # 6. Assemble complete dfont binary
+      #
+      # @return [Hash] Build result with:
+      #   - :binary [String] - Complete dfont binary
+      #   - :num_fonts [Integer] - Number of fonts packed
+      #   - :total_size [Integer] - Total size in bytes
+      def build
+        # Step 1: Serialize all fonts to SFNT binaries
+        sfnt_binaries = serialize_fonts
+
+        # Step 2: Build resource data section
+        resource_data = build_resource_data(sfnt_binaries)
+
+        # Step 3: Calculate expected resource map size
+        # Map header: 28 bytes
+        # Type list header: 2 bytes
+        # Type entry: 8 bytes
+        # References: 12 bytes each
+        map_size = 28 + 2 + 8 + (sfnt_binaries.size * 12)
+
+        # Step 4: Build resource map
+        resource_map = build_resource_map(sfnt_binaries, resource_data.bytesize, map_size)
+
+        # Step 5: Build header
+        header = build_header(resource_data.bytesize, resource_map.bytesize)
+
+        # Step 6: Assemble complete dfont binary
+        binary = header + resource_data + resource_map
+
+        # Store result
+        @result = {
+          binary: binary,
+          num_fonts: @fonts.size,
+          total_size: binary.bytesize,
+          format: :dfont,
+        }
+
+        @result
+      end
+
+      # Build dfont and write to file
+      #
+      # @param path [String] Output file path
+      # @return [Hash] Build result (same as build method)
+      def build_to_file(path)
+        result = build
+        File.binwrite(path, result[:binary])
+        result[:output_path] = path
+        result
+      end
+
+      private
+
+      # Validate fonts can be packed into dfont
+      #
+      # @return [void]
+      # @raise [Error] if validation fails
+      def validate_fonts!
+        validator = Validation::CollectionValidator.new
+        validator.validate!(@fonts, :dfont)
+      end
+
+      # Check if font is a web font
+      #
+      # @param font [Object] Font object
+      # @return [Boolean] true if WOFF or WOFF2
+      def web_font?(font)
+        font.class.name.include?("Woff")
+      end
+
+      # Serialize all fonts to SFNT binaries
+      #
+      # @return [Array<String>] Array of SFNT binaries
+      def serialize_fonts
+        @fonts.map do |font|
+          # Get all table data from font
+          tables_hash = font.table_data
+
+          # Determine sfnt version from font
+          sfnt_version = detect_sfnt_version(font)
+
+          # Write font to binary using FontWriter
+          FontWriter.write_font(tables_hash, sfnt_version: sfnt_version)
+        end
+      end
+
+      # Detect sfnt version from font
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Font object
+      # @return [Integer] sfnt version
+      def detect_sfnt_version(font)
+        if font.respond_to?(:header) && font.header.respond_to?(:sfnt_version)
+          font.header.sfnt_version
+        elsif font.respond_to?(:table_data)
+          # Auto-detect from tables
+          FontWriter.detect_sfnt_version(font.table_data)
+        else
+          0x00010000 # Default to TrueType
+        end
+      end
+
+      # Build resource fork header (16 bytes)
+      #
+      # @param data_length [Integer] Length of resource data section
+      # @param map_length [Integer] Length of resource map section
+      # @return [String] Binary header
+      def build_header(data_length, map_length)
+        # Resource fork header structure:
+        # - resource_data_offset (4 bytes): always 256 (0x100) for dfont
+        # - resource_map_offset (4 bytes): header_size + data_length
+        # - resource_data_length (4 bytes)
+        # - resource_map_length (4 bytes)
+
+        data_offset = 256 # Standard dfont offset (conceptual, points to useful data)
+        header_size = 16  # Actual header size in file
+        map_offset = header_size + data_length # Map comes after header + data
+
+        [
+          data_offset,
+          map_offset,
+          data_length,
+          map_length,
+        ].pack("N4")
+      end
+
+      # Build resource data section
+      #
+      # Contains all SFNT resources with 4-byte length prefix for each.
+      #
+      # @param sfnt_binaries [Array<String>] SFNT binaries
+      # @return [String] Resource data section binary
+      def build_resource_data(sfnt_binaries)
+        data = String.new(encoding: Encoding::BINARY)
+
+        # Add padding to reach offset 256 (header is 16 bytes, pad 240 bytes)
+        data << ("\0" * 240)
+
+        # Write each SFNT resource with length prefix
+        sfnt_binaries.each do |sfnt|
+          # 4-byte length prefix (big-endian)
+          data << [sfnt.bytesize].pack("N")
+          # SFNT data
+          data << sfnt
+        end
+
+        data
+      end
+
+      # Build resource map section
+      #
+      # Contains type list and reference list for all 'sfnt' resources.
+      #
+      # @param sfnt_binaries [Array<String>] SFNT binaries for offset calculation
+      # @param data_length [Integer] Actual resource data section length
+      # @param map_length [Integer] Actual resource map section length
+      # @return [String] Resource map section binary
+      def build_resource_map(sfnt_binaries, data_length, map_length)
+        map = String.new(encoding: Encoding::BINARY)
+
+        # Calculate offsets for header copy (must match main header)
+        data_offset = 256 # Standard dfont offset (conceptual)
+        header_size = 16 # Actual header size in file
+        map_offset = header_size + data_length # Map comes after header + data
+
+        # Resource map header (28 bytes):
+        # - Copy of resource header (16 bytes)
+        # - Handle to next resource map (4 bytes) - set to 0
+        # - File reference number (2 bytes) - set to 0
+        # - Resource file attributes (2 bytes) - set to 0
+        # - Offset to type list (2 bytes) - set to 28
+        # - Offset to name list (2 bytes) - calculated later
+
+        # Copy of resource header (must match main header exactly)
+        map << [data_offset, map_offset, data_length, map_length].pack("N4")
+
+        # Reserved fields
+        map << [0, 0, 0].pack("N n n")
+
+        # Offset to type list (from start of map)
+        map << [28].pack("n")
+
+        # Offset to name list (we don't use names, so point past all data)
+        type_list_size = 2 + 8 + (sfnt_binaries.size * 12) # type count + type entry + references
+        name_list_offset = 28 + type_list_size
+        map << [name_list_offset].pack("n")
+
+        # Type list:
+        # - Number of types - 1 (2 bytes) - we have 1 type ('sfnt')
+        # - Type entries (8 bytes each)
+        map << [0].pack("n") # 1 type - 1 = 0
+
+        # Type entry for 'sfnt':
+        # - Resource type (4 bytes): 'sfnt'
+        # - Number of resources - 1 (2 bytes)
+        # - Offset to reference list (2 bytes): from start of type list
+        map << "sfnt"
+        map << [sfnt_binaries.size - 1].pack("n")
+        reference_list_offset = 2 + 8 # After type count and type entry
+        map << [reference_list_offset].pack("n")
+
+        # Build reference list
+        map << build_reference_list(sfnt_binaries)
+
+        map
+      end
+
+      # Build reference list for 'sfnt' resources
+      #
+      # @param sfnt_binaries [Array<String>] SFNT binaries
+      # @return [String] Reference list binary
+      def build_reference_list(sfnt_binaries)
+        refs = String.new(encoding: Encoding::BINARY)
+
+        # Calculate offset for each resource in data section
+        # Offsets are relative to the start of the resource data section (not including padding)
+        # The resource_data_offset in header points to where resources actually start
+        current_offset = 0
+
+        sfnt_binaries.each_with_index do |sfnt, i|
+          # Resource reference (12 bytes):
+          # - Resource ID (2 bytes): start from 128
+          # - Name offset (2 bytes): -1 (no name)
+          # - Attributes (1 byte): 0
+          # - Data offset (3 bytes): offset in data section (24-bit big-endian)
+          # - Reserved (4 bytes): 0
+
+          resource_id = 128 + i
+          refs << [resource_id].pack("n")
+          refs << NO_NAME_OFFSET.pack("n") # No name
+          refs << ZERO_ATTRIBUTES.pack("C") # Attributes
+
+          # Pack 24-bit offset (3 bytes big-endian)
+          # Offset is from start of resource data section
+          offset_bytes = [current_offset].pack("N")[1..3]
+          refs << offset_bytes
+
+          refs << ZERO_RESERVED.pack("N") # Reserved
+
+          # Update offset for next resource
+          # Each resource has: 4-byte length + SFNT data
+          current_offset += 4 + sfnt.bytesize
+        end
+
+        refs
+      end
+    end
+  end
+end

data/lib/fontisan/collection/shared_logic.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Collection
+    # Shared logic for font collection classes
+    #
+    # This module provides common functionality for all collection types
+    # (TTC, OTC, dfont) to maintain DRY principles.
+    module SharedLogic
+      # Calculate table sharing statistics
+      #
+      # Analyzes which tables are shared between fonts and calculates
+      # space savings from deduplication.
+      #
+      # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Array of fonts
+      # @return [Models::TableSharingInfo] Sharing statistics
+      def calculate_table_sharing_for_fonts(fonts)
+        require_relative "../models/table_sharing_info"
+
+        # Build table hash map (checksum -> size)
+        table_map = {}
+        total_table_size = 0
+
+        fonts.each do |font|
+          font.tables.each do |entry|
+            key = entry.checksum
+            size = entry.table_length
+            table_map[key] ||= size
+            total_table_size += size
+          end
+        end
+
+        # Count unique vs shared
+        unique_tables = table_map.size
+        total_tables = fonts.sum { |f| f.tables.length }
+        shared_tables = total_tables - unique_tables
+
+        # Calculate space saved
+        unique_size = table_map.values.sum
+        space_saved = total_table_size - unique_size
+
+        # Calculate sharing percentage
+        sharing_pct = total_tables.positive? ? (shared_tables.to_f / total_tables * 100).round(2) : 0.0
+
+        Models::TableSharingInfo.new(
+          shared_tables: shared_tables,
+          unique_tables: unique_tables,
+          sharing_percentage: sharing_pct,
+          space_saved_bytes: space_saved,
+        )
+      end
+    end
+  end
+end

data/lib/fontisan/commands/convert_command.rb

@@ -2,6 +2,8 @@
 
 require_relative "base_command"
 require_relative "../pipeline/transformation_pipeline"
+require_relative "../converters/collection_converter"
+require_relative "../font_loader"
 
 module Fontisan
   module Commands
@@ -47,6 +49,7 @@ module Fontisan
       # @option options [Integer] :instance_index Named instance index
       # @option options [Boolean] :preserve_variation Preserve variation data (default: auto)
       # @option options [Boolean] :preserve_hints Preserve rendering hints (default: false)
+      # @option options [String] :target_format Target outline format for collections: 'preserve' (default), 'ttf', or 'otf'
       # @option options [Boolean] :no_validate Skip output validation
       # @option options [Boolean] :verbose Verbose output
       def initialize(font_path, options = {})
@@ -70,6 +73,7 @@ module Fontisan
         @instance_index = opts[:instance_index]
         @preserve_variation = opts[:preserve_variation]
         @preserve_hints = opts.fetch(:preserve_hints, false)
+        @collection_target_format = opts.fetch(:target_format, 'preserve').to_s
         @validate = !opts[:no_validate]
       end
 
@@ -81,6 +85,35 @@ module Fontisan
       def run
         validate_options!
 
+        # Check if input is a collection
+        if collection_file?
+          convert_collection
+        else
+          convert_single_font
+        end
+      rescue ArgumentError
+        # Let ArgumentError propagate for validation errors
+        raise
+      rescue StandardError => e
+        raise Error, "Conversion failed: #{e.message}"
+      end
+
+      private
+
+      # Check if input file is a collection
+      #
+      # @return [Boolean] true if collection
+      def collection_file?
+        FontLoader.collection?(font_path)
+      rescue StandardError
+        # If detection fails, assume single font
+        false
+      end
+
+      # Convert a single font (original implementation)
+      #
+      # @return [Hash] Result information
+      def convert_single_font
         puts "Converting #{File.basename(font_path)} to #{@target_format}..." unless @options[:quiet]
 
         # Build pipeline options
@@ -137,14 +170,86 @@ module Fontisan
           output_size: File.size(@output_path),
           variation_strategy: result[:details][:variation_strategy],
         }
-      rescue ArgumentError
-        # Let ArgumentError propagate for validation errors
-        raise
-      rescue StandardError => e
-        raise Error, "Conversion failed: #{e.message}"
       end
 
-      private
+      # Convert a collection
+      #
+      # @return [Hash] Result information
+      def convert_collection
+        # Determine target collection type from target format
+        target_type = collection_type_from_format(@target_format)
+
+        unless target_type
+          raise ArgumentError,
+                "Target format #{@target_format} is not a collection format. " \
+                "Use ttc, otc, or dfont for collection conversion."
+        end
+
+        puts "Converting collection to #{target_type.to_s.upcase}..." unless @options[:quiet]
+
+        # Use CollectionConverter
+        converter = Converters::CollectionConverter.new
+        result = converter.convert(
+          font_path,
+          target_type: target_type,
+          options: {
+            output: @output_path,
+            target_format: @collection_target_format,
+            verbose: @options[:verbose],
+          }
+        )
+
+        # Display results
+        unless @options[:quiet]
+          output_size = File.size(@output_path)
+          input_size = File.size(font_path)
+
+          puts "Conversion complete!"
+          puts "  Input:  #{font_path} (#{format_size(input_size)})"
+          puts "  Output: #{@output_path} (#{format_size(output_size)})"
+          puts "  Format: #{result[:source_type].to_s.upcase} → #{result[:target_type].to_s.upcase}"
+          puts "  Fonts:  #{result[:num_fonts]}"
+        end
+
+        {
+          success: true,
+          input_path: font_path,
+          output_path: @output_path,
+          source_format: result[:source_type],
+          target_format: result[:target_type],
+          input_size: File.size(font_path),
+          output_size: File.size(@output_path),
+          num_fonts: result[:num_fonts],
+        }
+      end
+
+      # Determine collection type from format
+      #
+      # @param format [Symbol] Target format
+      # @return [Symbol, nil] Collection type (:ttc, :otc, :dfont) or nil
+      def collection_type_from_format(format)
+        case format
+        when :ttc
+          :ttc
+        when :otc
+          :otc
+        when :dfont
+          :dfont
+        else
+          # Check output extension
+          ext = File.extname(@output_path).downcase
+          case ext
+          when ".ttc"
+            :ttc
+          when ".otc"
+            :otc
+          when ".dfont"
+            :dfont
+          else
+            nil
+          end
+        end
+      end
 
       # Parse coordinates string to hash
       #
@@ -194,6 +299,12 @@ module Fontisan
           :ttf
         when "otf", "opentype", "cff"
           :otf
+        when "ttc"
+          :ttc
+        when "otc"
+          :otc
+        when "dfont"
+          :dfont
         when "svg"
           :svg
         when "woff"
@@ -203,7 +314,7 @@ module Fontisan
         else
           raise ArgumentError,
                 "Unknown target format: #{format}. " \
-                "Supported: ttf, otf, svg, woff, woff2"
+                "Supported: ttf, otf, ttc, otc, dfont, svg, woff, woff2"
         end
       end