fontisan 0.2.5 → 0.2.7

data/lib/fontisan/commands/pack_command.rb

@@ -2,6 +2,7 @@
 
 require_relative "base_command"
 require_relative "../collection/builder"
+require_relative "../collection/dfont_builder"
 require_relative "../font_loader"
 
 module Fontisan
@@ -11,6 +12,7 @@ module Fontisan
     # This command provides CLI access to font collection creation functionality.
     # It loads multiple font files and combines them into a single TTC (TrueType Collection)
     # or OTC (OpenType Collection) file with shared table deduplication to save space.
+    # It also supports creating dfont (Apple Data Fork Font) suitcases.
     #
     # @example Pack fonts into TTC
     #   command = PackCommand.new(
@@ -30,13 +32,21 @@ module Fontisan
     #     analyze: true
     #   )
     #   result = command.run
+    #
+    # @example Pack into dfont
+    #   command = PackCommand.new(
+    #     ['font1.ttf', 'font2.otf'],
+    #     output: 'family.dfont',
+    #     format: :dfont
+    #   )
+    #   result = command.run
     class PackCommand
       # Initialize pack command
       #
       # @param font_paths [Array<String>] Paths to input font files
       # @param options [Hash] Command options
       # @option options [String] :output Output file path (required)
-      # @option options [Symbol, String] :format Format type (:ttc or :otc, default: :ttc)
+      # @option options [Symbol, String] :format Format type (:ttc, :otc, or :dfont, default: auto-detect)
       # @option options [Boolean] :optimize Enable table sharing optimization (default: true)
       # @option options [Boolean] :analyze Show analysis report before building (default: false)
       # @option options [Boolean] :verbose Enable verbose output (default: false)
@@ -45,7 +55,7 @@ module Fontisan
         @font_paths = font_paths
         @options = options
         @output_path = options[:output]
-        @format = parse_format(options[:format] || :ttc)
+        @format = options[:format] ? parse_format(options[:format]) : nil
         @optimize = options.fetch(:optimize, true)
         @analyze = options.fetch(:analyze, false)
         @verbose = options.fetch(:verbose, false)
@@ -55,16 +65,16 @@ module Fontisan
 
       # Execute the pack command
       #
-      # Loads all fonts, analyzes tables, and creates a TTC/OTC collection.
+      # Loads all fonts, analyzes tables, and creates a TTC/OTC/dfont collection.
       # Optionally displays analysis before building.
       #
       # @return [Hash] Result information with:
       #   - :output [String] - Output file path
       #   - :output_size [Integer] - Output file size in bytes
       #   - :num_fonts [Integer] - Number of fonts packed
-      #   - :format [Symbol] - Collection format (:ttc or :otc)
-      #   - :space_savings [Integer] - Bytes saved through sharing
-      #   - :sharing_percentage [Float] - Percentage of tables shared
+      #   - :format [Symbol] - Collection format (:ttc, :otc, or :dfont)
+      #   - :space_savings [Integer] - Bytes saved through sharing (TTC/OTC only)
+      #   - :sharing_percentage [Float] - Percentage of tables shared (TTC/OTC only)
       #   - :analysis [Hash] - Analysis report (if analyze option enabled)
       # @raise [ArgumentError] if options are invalid
       # @raise [Fontisan::Error] if packing fails
@@ -74,6 +84,46 @@ module Fontisan
         # Load all fonts
         fonts = load_fonts
 
+        # Auto-detect format if not specified
+        @format ||= auto_detect_format(fonts)
+        puts "Auto-detected format: #{@format}" if @verbose && !@options[:format]
+
+        # Build collection based on format
+        if @format == :dfont
+          build_dfont(fonts)
+        else
+          build_ttc_otc(fonts)
+        end
+      rescue Fontisan::Error => e
+        raise Fontisan::Error, "Collection packing failed: #{e.message}"
+      rescue StandardError => e
+        raise Fontisan::Error, "Unexpected error during packing: #{e.message}"
+      end
+
+      private
+
+      # Build dfont collection
+      #
+      # @param fonts [Array] Loaded fonts
+      # @return [Hash] Build result
+      def build_dfont(fonts)
+        puts "Building dfont suitcase..." if @verbose
+
+        builder = Collection::DfontBuilder.new(fonts)
+        result = builder.build_to_file(@output_path)
+
+        if @verbose
+          display_dfont_results(result)
+        end
+
+        result
+      end
+
+      # Build TTC/OTC collection
+      #
+      # @param fonts [Array] Loaded fonts
+      # @return [Hash] Build result
+      def build_ttc_otc(fonts)
         # Create builder
         builder = Collection::Builder.new(fonts, {
                                             format: @format,
@@ -98,13 +148,53 @@ module Fontisan
         end
 
         result
-      rescue Fontisan::Error => e
-        raise Fontisan::Error, "Collection packing failed: #{e.message}"
-      rescue StandardError => e
-        raise Fontisan::Error, "Unexpected error during packing: #{e.message}"
       end
 
-      private
+      # Auto-detect collection format based on fonts
+      #
+      # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Loaded fonts
+      # @return [Symbol] Detected format (:ttc, :otc, or :dfont)
+      def auto_detect_format(fonts)
+        # Check output extension first
+        ext = File.extname(@output_path).downcase
+        return :ttc if ext == ".ttc"
+        return :otc if ext == ".otc"
+        return :dfont if ext == ".dfont"
+
+        # Detect based on font types
+        has_truetype = fonts.any? { |f| truetype_font?(f) }
+        has_opentype = fonts.any? { |f| opentype_font?(f) }
+
+        if has_truetype && !has_opentype
+          :ttc  # All TrueType
+        elsif has_opentype
+          :otc  # Has OpenType/CFF fonts
+        else
+          :ttc  # Default to TTC
+        end
+      end
+
+      # Check if font is TrueType
+      #
+      # @param font [Object] Font object
+      # @return [Boolean]
+      def truetype_font?(font)
+        return false unless font.respond_to?(:header)
+
+        sfnt = font.header.sfnt_version
+        [0x00010000, 0x74727565].include?(sfnt) # 0x74727565 = 'true'
+      end
+
+      # Check if font is OpenType/CFF
+      #
+      # @param font [Object] Font object
+      # @return [Boolean]
+      def opentype_font?(font)
+        return false unless font.respond_to?(:header)
+
+        sfnt = font.header.sfnt_version
+        sfnt == 0x4F54544F # 'OTTO'
+      end
 
       # Validate command options
       #
@@ -125,17 +215,19 @@ module Fontisan
                 "Collection requires at least 2 fonts, got #{@font_paths.size}"
         end
 
-        # Validate format
-        unless %i[ttc otc].include?(@format)
+        # Validate format if specified
+        if @format && !%i[ttc otc dfont].include?(@format)
           raise ArgumentError,
-                "Invalid format: #{@format}. Must be :ttc or :otc"
+                "Invalid format: #{@format}. Must be :ttc, :otc, or :dfont"
         end
 
-        # Check output extension matches format
-        ext = File.extname(@output_path).downcase
-        expected_ext = @format == :ttc ? ".ttc" : ".otc"
-        if ext != expected_ext
-          warn "Warning: Output extension '#{ext}' doesn't match format '#{@format}' (expected '#{expected_ext}')"
+        # Warn if output extension doesn't match format (if format specified)
+        if @format
+          ext = File.extname(@output_path).downcase
+          expected_ext = ".#{@format}"
+          if ext != expected_ext
+            warn "Warning: Output extension '#{ext}' doesn't match format '#{@format}' (expected '#{expected_ext}')"
+          end
         end
       end
 
@@ -165,19 +257,21 @@ module Fontisan
       # Parse format option
       #
       # @param format [Symbol, String] Format option
-      # @return [Symbol] Parsed format (:ttc or :otc)
+      # @return [Symbol] Parsed format (:ttc, :otc, or :dfont)
       # @raise [ArgumentError] if format is invalid
       def parse_format(format)
-        return format if format.is_a?(Symbol) && %i[ttc otc].include?(format)
+        return format if format.is_a?(Symbol) && %i[ttc otc dfont].include?(format)
 
         case format.to_s.downcase
         when "ttc"
           :ttc
         when "otc"
           :otc
+        when "dfont"
+          :dfont
         else
           raise ArgumentError,
-                "Invalid format: #{format}. Must be 'ttc' or 'otc'"
+                "Invalid format: #{format}. Must be 'ttc', 'otc', or 'dfont'"
         end
       end
 
@@ -223,6 +317,19 @@ module Fontisan
         puts ""
       end
 
+      # Display dfont build results
+      #
+      # @param result [Hash] Build result
+      # @return [void]
+      def display_dfont_results(result)
+        puts "\n=== dfont Suitcase Created ==="
+        puts "Output: #{result[:output_path]}"
+        puts "Format: #{result[:format].upcase}"
+        puts "Fonts: #{result[:num_fonts]}"
+        puts "Size: #{format_bytes(result[:total_size])}"
+        puts ""
+      end
+
       # Format bytes for display
       #
       # @param bytes [Integer] Byte count

data/lib/fontisan/config/conversion_matrix.yml

@@ -177,6 +177,91 @@ conversions:
       Same-format copy operation. Decompresses and re-compresses WOFF2 data
       with Brotli, useful for normalizing compression or updating metadata.
 
+  # Collection format conversions (TTC/OTC/dfont)
+  # Same-format collection operations
+  - from: ttc
+    to: ttc
+    strategy: collection_copier
+    description: "Copy TrueType Collection"
+    status: implemented
+    notes: >
+      Same-format copy operation for TTC files. Preserves all fonts and
+      table sharing structure.
+
+  - from: otc
+    to: otc
+    strategy: collection_copier
+    description: "Copy OpenType Collection"
+    status: implemented
+    notes: >
+      Same-format copy operation for OTC files. Preserves all fonts and
+      table sharing structure.
+
+  - from: dfont
+    to: dfont
+    strategy: collection_copier
+    description: "Copy Apple dfont suitcase"
+    status: implemented
+    notes: >
+      Same-format copy operation for dfont files. Preserves all fonts in
+      the suitcase.
+
+  # Cross-collection conversions
+  - from: ttc
+    to: otc
+    strategy: collection_converter
+    description: "Convert TrueType Collection to OpenType Collection"
+    status: implemented
+    notes: >
+      Unpacks TTC, converts all TrueType fonts to OpenType/CFF format,
+      then repacks as OTC with table sharing optimization.
+
+  - from: otc
+    to: ttc
+    strategy: collection_converter
+    description: "Convert OpenType Collection to TrueType Collection"
+    status: implemented
+    notes: >
+      Unpacks OTC, converts all OpenType/CFF fonts to TrueType format,
+      then repacks as TTC with table sharing optimization.
+
+  - from: ttc
+    to: dfont
+    strategy: collection_converter
+    description: "Convert TrueType Collection to dfont suitcase"
+    status: implemented
+    notes: >
+      Unpacks TTC and repacks as Apple dfont suitcase. No outline conversion
+      needed as dfont supports TrueType fonts.
+
+  - from: otc
+    to: dfont
+    strategy: collection_converter
+    description: "Convert OpenType Collection to dfont suitcase"
+    status: implemented
+    notes: >
+      Unpacks OTC and repacks as Apple dfont suitcase. No outline conversion
+      needed as dfont supports OpenType/CFF fonts.
+
+  - from: dfont
+    to: ttc
+    strategy: collection_converter
+    description: "Convert dfont suitcase to TrueType Collection"
+    status: implemented
+    notes: >
+      Unpacks dfont suitcase and repacks as TTC. If dfont contains OpenType
+      fonts, they are converted to TrueType format. Only valid if all fonts
+      can be converted to TrueType.
+
+  - from: dfont
+    to: otc
+    strategy: collection_converter
+    description: "Convert dfont suitcase to OpenType Collection"
+    status: implemented
+    notes: >
+      Unpacks dfont suitcase and repacks as OTC. If dfont contains TrueType
+      fonts, they are converted to OpenType/CFF format.
+
 # Conversion compatibility matrix
 #
 # This section documents which source features are preserved in conversions.
@@ -247,4 +332,93 @@ compatibility:
     use_cases:
       - fallback: Emergency fallback for very old browsers
       - conversion: Intermediate format for font conversion workflows
-      - inspection: Easy-to-read format for font inspection
+      - inspection: Easy-to-read format for font inspection
+
+  collection_conversions:
+    ttc_to_otc:
+      preserves:
+        - all_fonts: All fonts in collection
+        - font_metrics: Font metrics for each font
+        - layout_features: Layout features for each font
+      limitations:
+        - outline_conversion_required: TrueType to CFF conversion applied
+        - hinting_loss: TrueType hinting not preserved in CFF
+      notes: >
+        Converts all TrueType fonts to OpenType/CFF format using the standard
+        TTF→OTF conversion pipeline, then repacks with table sharing.
+
+    otc_to_ttc:
+      preserves:
+        - all_fonts: All fonts in collection
+        - font_metrics: Font metrics for each font
+        - layout_features: Layout features for each font
+      limitations:
+        - outline_conversion_required: CFF to TrueType conversion applied
+        - hinting_loss: CFF hints not preserved in TrueType
+        - approximation: Cubic to quadratic curve approximation
+      notes: >
+        Converts all OpenType/CFF fonts to TrueType format using the standard
+        OTF→TTF conversion pipeline, then repacks with table sharing.
+
+    to_dfont:
+      preserves:
+        - all_fonts: All fonts in collection
+        - original_formats: Preserves original outline formats (TTF or OTF)
+        - font_metrics: All font metrics
+        - layout_features: All layout features
+      benefits:
+        - mixed_formats: dfont supports both TrueType and OpenType fonts
+        - mac_compatibility: Native Mac OS X suitcase format
+      limitations:
+        - platform_specific: Mac OS X only, not cross-platform
+        - no_table_sharing: dfont doesn't deduplicate tables like TTC/OTC
+      notes: >
+        Repackages fonts into Apple dfont suitcase format. No outline conversion
+        needed as dfont supports any SFNT font type (TTF, OTF, or mixed).
+
+    from_dfont:
+      preserves:
+        - all_fonts: All fonts in suitcase
+        - font_metrics: All font metrics
+        - layout_features: All layout features
+      limitations:
+        - conversion_may_be_required: Outline conversion if target requires specific format
+        - hinting_loss: If outline conversion occurs
+      benefits:
+        - cross_platform: TTC/OTC work on all platforms
+        - table_sharing: TTC/OTC optimize with table deduplication
+      notes: >
+        Extracts fonts from dfont suitcase and repacks into TTC or OTC.
+        Outline conversion may occur depending on target format requirements.
+
+# Collection format rules
+collection_rules:
+  ttc:
+    required_format: truetype
+    allows_mixed: false
+    spec_compliance: opentype_spec
+    description: >
+      TrueType Collection per OpenType specification. Contains only TrueType
+      fonts (glyf/loca tables). CFF fonts are not allowed.
+
+  otc:
+    required_format: cff_preferred
+    allows_mixed: true
+    spec_compliance: opentype_1.8
+    description: >
+      OpenType Collection per OpenType 1.8 specification. Requires at least
+      one CFF font. Fontisan extension allows mixed TTF+OTF for flexibility.
+
+  dfont:
+    required_format: any_sfnt
+    allows_mixed: true
+    spec_compliance: apple_proprietary
+    description: >
+      Apple dfont (Data Fork Font) suitcase. Contains Mac font suitcase
+      resources (FOND, NFNT, sfnt). Supports any SFNT fonts (TrueType,
+      OpenType/CFF, or mixed). Mac OS X specific, not cross-platform.
+
+  prohibited:
+    - web_fonts_in_collections: >
+        WOFF and WOFF2 fonts cannot be included in collections (TTC, OTC, or dfont).
+        Web fonts are designed for single-font web delivery only.

data/lib/fontisan/constants.rb

@@ -25,6 +25,14 @@ module Fontisan
     # SFNT version for OpenType fonts with CFF outlines ('OTTO')
     SFNT_VERSION_OTTO = 0x4F54544F
 
+    # Apple 'true' TrueType signature (alternate to 0x00010000)
+    SFNT_VERSION_TRUE = 0x74727965 # 'true' in ASCII
+
+    # dfont resource fork signatures
+    DFONT_RESOURCE_HEADER = "\x00\x00\x01\x00"
+    SFNT_RESOURCE_TYPE = "sfnt"
+    FOND_RESOURCE_TYPE = "FOND"
+
     # Head table tag identifier.
     # The 'head' table contains global font header information including
     # the checksum adjustment field.