fontisan 0.2.0 → 0.2.1

data/README.adoc

@@ -71,7 +71,7 @@ gem install fontisan
 * Collection management (pack/unpack TTC/OTC files with table deduplication)
 * Support for TTF, OTF, TTC, OTC font formats (production ready)
 * WOFF format support (reading complete, writing functional, pending full integration)
-* WOFF2 format support (reading partial, writing planned)
+* WOFF2 format support (reading complete with table transformations, writing planned)
 * SVG font generation (complete)
 * TTX/YAML/JSON export (complete)
 * Command-line interface with 18 commands
@@ -85,8 +85,14 @@ gem install fontisan
 * Compound glyph decomposition with transformation support (complete)
 * CFF subroutine optimization for space-efficient OTF generation (preview mode)
 * Various loading modes for high-performance font indexing (5x faster)
+* Hint preservation during TTF ↔ OTF conversion (optional, partially complete)
+* CFF2 variable font support for PostScript hint conversion (complete)
 
-NOTE: TTF ↔ OTF outline format conversion is in active development (Phase 1, ~80% complete). The universal outline model, CFF builders, curve converter, and compound glyph support are fully functional. Simple and compound glyphs convert successfully. See link:docs/IMPLEMENTATION_STATUS_V4.md[Implementation Status] for detailed progress tracking.
+NOTE: TTF ↔ OTF outline format conversion is in active development (~80%
+complete). The universal outline model, CFF builders, curve converter, and
+compound glyph support are fully functional. Simple and compound glyphs convert
+successfully. See link:docs/IMPLEMENTATION_STATUS_V4.md[Implementation Status]
+for detailed progress tracking.
 
 
 == Loading Modes
@@ -160,6 +166,7 @@ font.table_available?(tag)  # => boolean
 # Access restricted based on mode
 font.table(tag)  # => Returns table or raises error
 ----
+"
 
 
 
@@ -256,7 +263,7 @@ Fontisan supports bidirectional conversion between TrueType (TTF) and OpenType/C
 
 The outline converter enables transformation between glyph outline formats:
 
-* **TrueType (TTF)**: Uses quadratic Bézier curves stored in glyf/loc tables
+* **TrueType (TTF)**: Uses quadratic Bézier curves stored in glyf/loca tables
 * **OpenType/CFF (OTF)**: Uses cubic Bézier curves stored in CFF table
 
 Conversion uses a format-agnostic universal outline model as an intermediate representation, ensuring high-quality results while preserving glyph metrics and bounding boxes.
@@ -297,6 +304,11 @@ fontisan convert font.ttf --to cff --output font.otf
 
 ==== Validation
 
+Font integrity validation is now enabled by default for all conversions.
+The validator ensures proper OpenType checksum calculation including correct
+handling of the head table's checksumAdjustment field per the OpenType
+specification.
+
 After conversion, validate the output font:
 
 [source,bash]
@@ -1325,6 +1337,148 @@ Instance 2 position:    75 300
 ----
 ====
 
+==== Generate static instances from variable fonts
+
+Generate static font instances from variable fonts at specific variation coordinates
+and output in any supported format (TTF, OTF, WOFF).
+
+Syntax:
+
+[source,shell]
+----
+$ fontisan instance VARIABLE_FONT [OPTIONS]
+----
+
+Where,
+
+`VARIABLE_FONT`:: Path to the variable font file
+`OPTIONS`:: Instance generation options
+
+Options:
+
+`--wght VALUE`:: Weight axis value
+`--wdth VALUE`:: Width axis value
+`--slnt VALUE`:: Slant axis value
+`--ital VALUE`:: Italic axis value
+`--opsz VALUE`:: Optical size axis value
+`--to FORMAT`:: Output format: `ttf` (default), `otf`, `woff`, or `woff2`
+`--output FILE`:: Output file path
+`--optimize`:: Enable CFF optimization for OTF output
+`--named-instance INDEX`:: Use named instance by index
+`--list-instances`:: List available named instances
+`--validate`:: Validate font before generation
+`--dry-run`:: Preview instance without generating
+`--progress`:: Show progress during generation
+
+
+.Generate bold instance at wght=700
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --wght 700 --output bold.ttf
+
+Generating instance... done
+Writing output... done
+Static font instance written to: bold.ttf
+----
+====
+
+.Generate instance and convert to OTF
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --wght 300 --to otf --output light.otf
+
+Generating instance... done
+Writing output... done
+Static font instance written to: light.otf
+----
+====
+
+.Generate instance and convert to WOFF
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --wght 600 --to woff --output semibold.woff
+
+Generating instance... done
+Writing output... done
+Static font instance written to: semibold.woff
+----
+====
+
+.Generate instance with multiple axes
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --wght 600 --wdth 75 --output condensed.ttf
+
+Generating instance... done
+Writing output... done
+Static font instance written to: condensed.ttf
+----
+====
+
+.List available named instances
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --list-instances
+
+Available named instances:
+
+  [0] Instance 4
+    Coordinates:
+      wdth: 75.0
+      wght: 200.0
+
+  [1] Instance 5
+    Coordinates:
+      wdth: 75.0
+      wght: 250.0
+
+  [2] Instance 6
+    Coordinates:
+      wdth: 75.0
+      wght: 300.0
+----
+====
+
+.Use named instance
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --named-instance 0 --output thin.ttf
+----
+====
+
+.Preview instance generation (dry-run)
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --wght 700 --dry-run
+
+Dry-run mode: Preview of instance generation
+
+Coordinates:
+  wght: 700.0
+
+Output would be written to: variable-instance.ttf
+Output
+
+ format: same as input
+
+Use without --dry-run to actually generate the instance.
+----
+====
+
 ==== Optical size information
 
 Display optical size range from the OS/2 table for fonts designed for specific
@@ -1644,7 +1798,7 @@ Font 3: Noto Serif CJK TC
 
 ===== Show collection info
 
-Show detailed information about a TrueType Collection (TTC), OpenType Collection
+Show detailed information about a TrueType Collection (TTC) or OpenType Collection
 (OTC), including the number of fonts and metadata for each font.
 
 [source,shell]

data/Rakefile

@@ -9,7 +9,8 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 namespace :fixtures do
-  fixtures_dir = "spec/fixtures/fonts"
+  # Load centralized fixture configuration
+  require_relative "spec/support/fixture_fonts"
 
   # Helper method to download a single file
   def download_single_file(name, url, target_path)
@@ -30,61 +31,58 @@ namespace :fixtures do
     require "open-uri"
     require "zip"
 
-    zip_file = "#{target_dir}/#{name}.zip"
-
     puts "[fixtures:download] Downloading #{name}..."
     FileUtils.mkdir_p(target_dir)
 
-    URI.open(url) do |remote|
-      File.binwrite(zip_file, remote.read)
+    # Create a manual temp file path - OS will clean up temp files automatically
+    temp_path = File.join(Dir.tmpdir, "fontisan_#{name}_#{Process.pid}_#{rand(10000)}.zip")
+
+    # Download using IO.copy_stream for better Windows compatibility
+    URI.open(url, "rb") do |remote|
+      File.open(temp_path, "wb") do |file|
+        IO.copy_stream(remote, file)
+      end
     end
 
     puts "[fixtures:download] Extracting #{name}..."
-    Zip::File.open(zip_file) do |zip|
-      zip.each do |entry|
-        dest_path = File.join(target_dir, entry.name)
+
+    # Open zip file and ensure it's fully closed before we're done
+    zip_file = Zip::File.open(temp_path)
+    begin
+      zip_file.each do |entry|
+        # Skip macOS metadata files and directories
+        next if entry.name.start_with?("__MACOSX/") || entry.name.include?("/._")
+        next if entry.directory?
+
+        # Ensure entry.name is relative by stripping leading slashes
+        relative_name = entry.name.sub(%r{^/+}, "")
+
+        dest_path = File.join(target_dir, relative_name)
         FileUtils.mkdir_p(File.dirname(dest_path))
-        entry.extract(dest_path) unless File.exist?(dest_path)
+
+        # Skip if file already exists
+        next if File.exist?(dest_path)
+
+        # Write the file content directly using binary mode
+        File.open(dest_path, "wb") do |file|
+          IO.copy_stream(entry.get_input_stream, file)
+        end
       end
+    ensure
+      # Explicitly close the zip file to release file handle on Windows
+      zip_file.close if zip_file
     end
 
-    FileUtils.rm(zip_file)
+    # Temp file left in Dir.tmpdir - OS will clean it up automatically
+
     puts "[fixtures:download] #{name} downloaded successfully"
   rescue LoadError => e
     warn "[fixtures:download] Error: Required gem not installed. Please run: gem install rubyzip"
     raise e
   end
 
-  # Font configurations with target directories and marker files
-  # All fonts are downloaded via Rake
-  fonts = {
-    "NotoSans" => {
-      url: "https://github.com/notofonts/notofonts.github.io/raw/refs/heads/main/fonts/NotoSans/full/ttf/NotoSans-Regular.ttf",
-      target_dir: fixtures_dir.to_s,
-      marker: "#{fixtures_dir}/NotoSans-Regular.ttf",
-      single_file: true,
-    },
-    "Libertinus" => {
-      url: "https://github.com/alerque/libertinus/releases/download/v7.051/Libertinus-7.051.zip",
-      target_dir: "#{fixtures_dir}/libertinus",
-      marker: "#{fixtures_dir}/libertinus/Libertinus-7.051/static/OTF/LibertinusSerif-Regular.otf",
-    },
-    "MonaSans" => {
-      url: "https://github.com/github/mona-sans/releases/download/v2.0/MonaSans.zip",
-      target_dir: "#{fixtures_dir}/MonaSans",
-      marker: "#{fixtures_dir}/MonaSans/MonaSans/variable/MonaSans[wdth,wght].ttf",
-    },
-    "NotoSerifCJK" => {
-      url: "https://github.com/notofonts/noto-cjk/releases/download/Serif2.003/01_NotoSerifCJK.ttc.zip",
-      target_dir: "#{fixtures_dir}/NotoSerifCJK",
-      marker: "#{fixtures_dir}/NotoSerifCJK/NotoSerifCJK.ttc",
-    },
-    "NotoSerifCJK-VF" => {
-      url: "https://github.com/notofonts/noto-cjk/releases/download/Serif2.003/02_NotoSerifCJK-OTF-VF.zip",
-      target_dir: "#{fixtures_dir}/NotoSerifCJK-VF",
-      marker: "#{fixtures_dir}/NotoSerifCJK-VF/Variable/OTC/NotoSerifCJK-VF.otf.ttc",
-    },
-  }
+  # Get font configurations from centralized source
+  fonts = FixtureFonts.rakefile_config
 
   # Create file tasks for each font
   fonts.each do |name, config|
@@ -102,13 +100,12 @@ namespace :fixtures do
 
   desc "Clean downloaded fixtures"
   task :clean do
-    %w[libertinus MonaSans NotoSerifCJK NotoSerifCJK-VF
-       NotoSans-Regular.ttf].each do |dir|
-      path = File.join(fixtures_dir, dir)
-      if File.exist?(path)
-        FileUtils.rm_rf(path)
-        puts "[fixtures:clean] Removed #{path}"
-      end
+    fonts.values.map { |config| config[:target_dir] }.each do |path|
+      next unless File.exist?(path)
+
+      puts "[fixtures:clean] Removing #{path}..."
+      FileUtils.rm_rf(path)
+      puts "[fixtures:clean] Removed #{path}"
     end
   end
 end

data/lib/fontisan/cli.rb

@@ -25,16 +25,21 @@ module Fontisan
                          desc: "Suppress non-error output",
                          aliases: "-q"
 
-    desc "info FONT_FILE", "Display font information"
+    desc "info PATH", "Display font information"
     # 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 => e
+      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 +200,79 @@ 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
+      convert_options[:instance_coordinates] = instance_coords if instance_coords.any?
+
+      command = Commands::ConvertCommand.new(font_file, convert_options)
       command.run
     rescue Errno::ENOENT, Error => e
       handle_error(e)
@@ -444,6 +481,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,64 @@ 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