fontisan 0.2.0 → 0.2.2

data/lib/fontisan/cli.rb

@@ -25,16 +25,24 @@ module Fontisan
                          desc: "Suppress non-error output",
                          aliases: "-q"
 
-    desc "info FONT_FILE", "Display font information"
+    desc "info PATH", "Display font information"
+    option :brief, type: :boolean, default: false,
+                   desc: "Brief mode - only essential info (5x faster, uses metadata loading)",
+                   aliases: "-b"
     # Extract and display comprehensive font metadata.
     #
-    # @param font_file [String] Path to the font file
-    def info(font_file)
-      command = Commands::InfoCommand.new(font_file, options)
-      result = command.run
-      output_result(result)
-    rescue Errno::ENOENT, Error => e
-      handle_error(e)
+    # @param path [String] Path to the font file or collection
+    def info(path)
+      command = Commands::InfoCommand.new(path, options)
+      info = command.run
+      output_result(info) unless options[:quiet]
+    rescue Errno::ENOENT
+      if options[:verbose]
+        raise
+      else
+        warn "File not found: #{path}" unless options[:quiet]
+        exit 1
+      end
     end
 
     desc "ls FILE", "List contents (fonts in collection or font summary)"
@@ -195,47 +203,82 @@ module Fontisan
 
     desc "convert FONT_FILE", "Convert font to different format"
     option :to, type: :string, required: true,
-                desc: "Target format (ttf, otf, woff2, svg)",
+                desc: "Target format (ttf, otf, woff, woff2)",
                 aliases: "-t"
     option :output, type: :string, required: true,
                     desc: "Output file path",
                     aliases: "-o"
-    option :optimize, type: :boolean, default: false,
-                      desc: "Optimize CFF with subroutines (TTF→OTF only)"
-    option :min_pattern_length, type: :numeric, default: 10,
-                                desc: "Minimum pattern length for subroutines"
-    option :max_subroutines, type: :numeric, default: 65_535,
-                             desc: "Maximum number of subroutines"
-    option :optimize_ordering, type: :boolean, default: true,
-                               desc: "Optimize subroutine ordering by frequency"
-    # Convert a font to a different format.
+    option :coordinates, type: :string,
+                         desc: "Instance coordinates (e.g., wght=700,wdth=100)",
+                         aliases: "-c"
+    option :instance_index, type: :numeric,
+                            desc: "Named instance index",
+                            aliases: "-n"
+    option :preserve_variation, type: :boolean,
+                                desc: "Force variation preservation (auto-detected by default)"
+    option :no_validate, type: :boolean, default: false,
+                         desc: "Skip output validation"
+    option :preserve_hints, type: :boolean, default: false,
+                            desc: "Preserve rendering hints during conversion (TTF→OTF preservations may be limited)"
+    option :wght, type: :numeric,
+                  desc: "Weight axis value (alternative to --coordinates)"
+    option :wdth, type: :numeric,
+                  desc: "Width axis value (alternative to --coordinates)"
+    option :slnt, type: :numeric,
+                  desc: "Slant axis value (alternative to --coordinates)"
+    option :ital, type: :numeric,
+                  desc: "Italic axis value (alternative to --coordinates)"
+    option :opsz, type: :numeric,
+                  desc: "Optical size axis value (alternative to --coordinates)"
+    # Convert a font to a different format using the universal transformation pipeline.
     #
     # Supported conversions:
-    # - Same format (ttf→ttf, otf→otf): Copy/optimize
-    # - TTF ↔ OTF: Outline format conversion (foundation)
-    # - Future: WOFF2 compression, SVG export
+    # - TTF ↔ OTF: Outline format conversion
+    # - WOFF/WOFF2: Web font packaging
+    # - Variable fonts: Automatic variation preservation or instance generation
+    #
+    # Variable Font Operations:
+    # The pipeline automatically detects whether variation data can be preserved based on
+    # source and target formats. For same outline family (TTF→WOFF or OTF→WOFF2), variation
+    # is preserved automatically. For cross-family conversions (TTF↔OTF), an instance is
+    # generated unless --preserve-variation is explicitly set.
     #
-    # Subroutine Optimization (--optimize):
-    # When converting TTF→OTF, you can enable automatic CFF subroutine generation
-    # to reduce file size. This analyzes repeated byte patterns across glyphs and
-    # creates shared subroutines, typically saving 30-50% in CFF table size.
+    # Instance Generation:
+    # Use --coordinates to specify exact axis values (e.g., wght=700,wdth=100) or
+    # --instance-index to use a named instance. Individual axis options (--wght, --wdth)
+    # are also supported for convenience.
     #
     # @param font_file [String] Path to the font file
     #
     # @example Convert TTF to OTF
     #   fontisan convert font.ttf --to otf --output font.otf
     #
-    # @example Convert with optimization
-    #   fontisan convert font.ttf --to otf --output font.otf --optimize --verbose
+    # @example Generate bold instance at specific coordinates
+    #   fontisan convert variable.ttf --to ttf --output bold.ttf --coordinates "wght=700,wdth=100"
+    #
+    # @example Generate bold instance using individual axis options
+    #   fontisan convert variable.ttf --to ttf --output bold.ttf --wght 700
+    #
+    # @example Use named instance
+    #   fontisan convert variable.ttf --to woff2 --output bold.woff2 --instance-index 0
     #
-    # @example Convert with custom optimization parameters
-    #   fontisan convert font.ttf --to otf --output font.otf --optimize \
-    #     --min-pattern-length 15 --max-subroutines 10000
+    # @example Force variation preservation (if compatible)
+    #   fontisan convert variable.ttf --to woff2 --output variable.woff2 --preserve-variation
     #
-    # @example Copy/optimize TTF
-    #   fontisan convert font.ttf --to ttf --output optimized.ttf
+    # @example Convert without validation
+    #   fontisan convert font.ttf --to otf --output font.otf --no-validate
     def convert(font_file)
-      command = Commands::ConvertCommand.new(font_file, options)
+      # Build instance coordinates from axis options
+      instance_coords = build_instance_coordinates(options)
+
+      # Merge coordinates into options
+      convert_options = options.to_h.dup
+      if instance_coords.any?
+        convert_options[:instance_coordinates] =
+          instance_coords
+      end
+
+      command = Commands::ConvertCommand.new(font_file, convert_options)
       command.run
     rescue Errno::ENOENT, Error => e
       handle_error(e)
@@ -311,7 +354,8 @@ module Fontisan
     option :verbose, type: :boolean, default: false,
                      desc: "Show detailed validation information"
     def validate(font_file)
-      command = Commands::ValidateCommand.new(font_file, verbose: options[:verbose])
+      command = Commands::ValidateCommand.new(font_file,
+                                              verbose: options[:verbose])
       exit command.run
     end
 
@@ -444,6 +488,20 @@ module Fontisan
 
     private
 
+    # Build instance coordinates from CLI axis options
+    #
+    # @param options [Hash] CLI options
+    # @return [Hash] Coordinates hash
+    def build_instance_coordinates(options)
+      coords = {}
+      coords["wght"] = options[:wght].to_f if options[:wght]
+      coords["wdth"] = options[:wdth].to_f if options[:wdth]
+      coords["slnt"] = options[:slnt].to_f if options[:slnt]
+      coords["ital"] = options[:ital].to_f if options[:ital]
+      coords["opsz"] = options[:opsz].to_f if options[:opsz]
+      coords
+    end
+
     # Output the result in the requested format.
     #
     # @param result [Object] The result object to output

data/lib/fontisan/collection/builder.rb

@@ -164,6 +164,9 @@ module Fontisan
           raise Error, "Format mismatch: #{incompatible.join(', ')}"
         end
 
+        # Check variable font compatibility
+        validate_variation_compatibility! if variable_fonts_in_collection?
+
         # Check all fonts have required tables
         @fonts.each_with_index do |font, index|
           required_tables = %w[head hhea maxp]
@@ -177,6 +180,26 @@ module Fontisan
         true
       end
 
+      # Check if collection contains variable fonts
+      #
+      # @return [Boolean] true if any font has fvar table
+      def variable_fonts_in_collection?
+        @fonts.any? { |font| font.has_table?("fvar") }
+      end
+
+      # Validate variable font compatibility
+      #
+      # Ensures all variable fonts in the collection are compatible:
+      # - All must be same variation type (TrueType or CFF2)
+      # - All must have the same axes
+      #
+      # @return [void]
+      # @raise [Error] if variable fonts are incompatible
+      def validate_variation_compatibility!
+        validate_all_same_variation_type!
+        validate_same_axes!
+      end
+
       private
 
       # Load configuration from file
@@ -255,6 +278,65 @@ module Fontisan
 
         incompatible
       end
+
+      # Validate all variable fonts use same variation type
+      #
+      # @return [void]
+      # @raise [Error] if mixing TrueType and CFF2 variable fonts
+      def validate_all_same_variation_type!
+        variable_fonts = @fonts.select { |f| f.has_table?("fvar") }
+        return if variable_fonts.empty?
+
+        ttf_count = variable_fonts.count { |f| f.has_table?("glyf") }
+        otf_count = variable_fonts.count { |f| f.has_table?("CFF2") }
+
+        if ttf_count.positive? && otf_count.positive?
+          raise Error,
+                "Cannot mix TrueType and CFF2 variable fonts in collection"
+        end
+      end
+
+      # Validate all variable fonts have same axes
+      #
+      # @return [void]
+      # @raise [Error] if variable fonts have different axes
+      def validate_same_axes!
+        variable_fonts = @fonts.select { |f| f.has_table?("fvar") }
+        return if variable_fonts.size < 2
+
+        first_axes = extract_axes(variable_fonts.first)
+        variable_fonts.each_with_index do |font, index|
+          font_axes = extract_axes(font)
+          unless axes_match?(font_axes, first_axes)
+            raise Error,
+                  "Variable font #{index} has different axes. " \
+                  "Expected: #{first_axes.join(', ')}, " \
+                  "Got: #{font_axes.join(', ')}"
+          end
+        end
+      end
+
+      # Extract axis tags from a font's fvar table
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Font to extract axes from
+      # @return [Array<String>] Sorted array of axis tags
+      def extract_axes(font)
+        return [] unless font.has_table?("fvar")
+
+        fvar_table = font.table("fvar")
+        return [] unless fvar_table.respond_to?(:axes)
+
+        fvar_table.axes.map(&:axis_tag).sort
+      end
+
+      # Check if two axis arrays match
+      #
+      # @param axes1 [Array<String>] First axis array
+      # @param axes2 [Array<String>] Second axis array
+      # @return [Boolean] true if axes match
+      def axes_match?(axes1, axes2)
+        axes1 == axes2
+      end
     end
   end
 end

data/lib/fontisan/collection/offset_calculator.rb

@@ -165,6 +165,7 @@ module Fontisan
           end
         end
 
+        # rubocop:disable Style/CombinableLoops
         # First, assign offsets to shared tables
         # Shared tables are stored once and referenced by multiple fonts
         canonical_tables.each do |canonical_id, info|
@@ -182,6 +183,7 @@ module Fontisan
           @offsets[:table_offsets][canonical_id] = current_offset
           current_offset = align_offset(current_offset + info[:size])
         end
+        # rubocop:enable Style/CombinableLoops
       end
 
       # Align offset to TABLE_ALIGNMENT boundary

data/lib/fontisan/collection/table_deduplicator.rb

@@ -15,6 +15,12 @@ module Fontisan
     #   sharing_map = deduplicator.build_sharing_map
     #   canonical_tables = deduplicator.canonical_tables
     class TableDeduplicator
+      # Tables that can be shared in variable font collections if identical
+      VARIATION_SHAREABLE_TABLES = %w[fvar avar STAT HVAR VVAR MVAR].freeze
+
+      # Tables that must remain font-specific in variable fonts
+      VARIATION_FONT_SPECIFIC_TABLES = %w[gvar CFF2].freeze
+
       # Canonical tables (unique table data)
       # @return [Hash<String, Hash>] Map of table tag to canonical versions
       attr_reader :canonical_tables
@@ -62,6 +68,9 @@ module Fontisan
         # First pass: collect all unique tables
         collect_canonical_tables
 
+        # Handle variable font table deduplication
+        deduplicate_variation_tables if has_variable_fonts?
+
         # Second pass: build sharing map for each font
         build_font_sharing_references
 
@@ -115,6 +124,73 @@ module Fontisan
 
       private
 
+      # Check if any font is a variable font
+      #
+      # @return [Boolean] true if any font has fvar table
+      def has_variable_fonts?
+        @fonts.any? { |font| font.has_table?("fvar") }
+      end
+
+      # Deduplicate variable font tables
+      #
+      # Handles special logic for variable font tables:
+      # - Share tables that are identical across fonts (fvar, avar, etc.)
+      # - Keep font-specific tables separate (gvar, CFF2)
+      #
+      # @return [void]
+      def deduplicate_variation_tables
+        # Share tables that are identical across fonts
+        VARIATION_SHAREABLE_TABLES.each do |tag|
+          share_if_identical(tag)
+        end
+
+        # Never share font-specific variation tables
+        VARIATION_FONT_SPECIFIC_TABLES.each do |tag|
+          keep_separate(tag)
+        end
+      end
+
+      # Share table if identical across all fonts that have it
+      #
+      # @param tag [String] Table tag
+      # @return [void]
+      def share_if_identical(tag)
+        # Get all instances of this table
+        tables = @fonts.map { |f| f.table_data[tag] }.compact
+        return if tables.empty?
+
+        # Check if all instances are identical
+        nil if tables.uniq.length > 1
+
+        # All instances are identical, mark as shareable
+        # The normal deduplication logic will handle this
+      end
+
+      # Ensure table stays separate for each font
+      #
+      # @param tag [String] Table tag
+      # @return [void]
+      def keep_separate(tag)
+        # Mark each font's instance as non-shareable
+        @fonts.each_with_index do |font, _font_index|
+          next unless font.has_table?(tag)
+
+          # Find this font's canonical table for this tag
+          table_data = font.table_data[tag]
+          checksum = calculate_checksum(table_data)
+
+          # Ensure canonical table exists
+          @canonical_tables[tag] ||= {}
+          canonical_id = @checksum_to_canonical.dig(tag, checksum)
+
+          next unless canonical_id && @canonical_tables[tag][canonical_id]
+
+          # Mark as non-shareable
+          @canonical_tables[tag][canonical_id][:shared] = false
+          @canonical_tables[tag][canonical_id][:font_specific] = true
+        end
+      end
+
       # Collect all unique (canonical) tables across all fonts
       #
       # Identifies unique table content based on checksum and stores one

data/lib/fontisan/commands/base_command.rb

@@ -66,13 +66,32 @@ module Fontisan
       # @raise [InvalidFontError] for corrupted or unknown formats
       # @raise [Error] for other loading failures
       def load_font
+        # BaseCommand is for inspection - reject compressed formats first
+        # Check file signature before attempting to load
+        File.open(@font_path, "rb") do |io|
+          signature = io.read(4)
+
+          if signature == "wOFF"
+            raise UnsupportedFormatError,
+                  "Unsupported font format: WOFF files must be decompressed first. " \
+                  "Use ConvertCommand to convert WOFF to TTF/OTF."
+          elsif signature == "wOF2"
+            raise UnsupportedFormatError,
+                  "Unsupported font format: WOFF2 files must be decompressed first. " \
+                  "Use ConvertCommand to convert WOFF2 to TTF/OTF."
+          end
+        end
+
+        # Brief mode uses metadata loading for 5x faster parsing
+        mode = @options[:brief] ? LoadingModes::METADATA : (@options[:mode] || LoadingModes::FULL)
+
         # ConvertCommand and similar commands need all tables loaded upfront
         # Use mode and lazy from options, or sensible defaults
         FontLoader.load(
           @font_path,
           font_index: @options[:font_index] || 0,
-          mode: @options[:mode] || LoadingModes::FULL,
-          lazy: @options.key?(:lazy) ? @options[:lazy] : false
+          mode: mode,
+          lazy: @options.key?(:lazy) ? @options[:lazy] : false,
         )
       rescue Errno::ENOENT
         # Re-raise file not found as-is