fontisan 0.4.47 → 0.4.48

data/lib/fontisan/byte_ops.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Fontisan
+  # Routing rules, result rebuilding and error rebuilding shared by the engine
+  # tiers that serve convert, extract, instance and subset
+  # ({Fontisan::Native}, {Fontisan::Ffi}). Included into their singleton
+  # classes; the methods are private to the tier.
+  module ByteOps
+    # Convert target codes of the engine (extension and C ABI alike).
+    TARGET_CODES = { ttf: 0, otf: 1, woff: 2, woff2: 3, ttc: 4, otc: 5 }.freeze
+    SINGLE_TARGETS = %i[ttf otf woff woff2].freeze
+    COLLECTION_TARGETS = %i[ttc otc woff2].freeze
+    CONVERT_OPTIONS = %i[to output timestamp quiet].freeze
+    SUBSET_PROFILES = %w[web pdf minimal].freeze
+    MAX_CODEPOINT = 0x10FFFF
+
+    BYTE_OPERATIONS = %i[convert extract instance subset].freeze
+
+    # "<ruby class>: <message>": how the engine reports a Ruby exception it
+    # mirrors (the byte operations carry one class and one message, no chain).
+    FAILURE_MESSAGE = /\A([A-Z]\w*(?:::\w+)*): (.*)\z/m
+    # The engine's text for a file that is no font; Ruby's is InvalidFontError.
+    UNRECOGNISED_FORMAT_MESSAGE = "Conversion failed: unrecognised font format"
+
+    private
+
+    # Whether the engine honours +options+ for +operation+ (one of
+    # {BYTE_OPERATIONS}); the first reuse point for tier routing.
+    def byte_options?(operation, options, path)
+      case operation
+      when :convert then convert_options?(options, path)
+      when :extract then extract_options?(options)
+      when :instance then instance_options?(options, path)
+      when :subset then subset_options?(options, path)
+      else false
+      end
+    end
+
+    # A collection: `ttcf`, or a WOFF2 whose flavor is `ttcf`.
+    def collection_file?(path)
+      head = File.binread(path, 8) or return false
+      head.start_with?("ttcf") || (head.start_with?("wOF2") && head.byteslice(4, 4) == "ttcf")
+    rescue SystemCallError
+      false
+    end
+
+    # `.otc` decision (card 2f): Ruby picks a collection's source type from
+    # the input path's extension (`.otc` vs anything else), and the engine
+    # only sees bytes and assumes `.ttc`. No hint is passed: `.otc`
+    # inputs stay on the Ruby tier.
+    def otc_hint?(path)
+      File.extname(path).casecmp?(".otc")
+    end
+
+    # Single target `to:` (no multi-format), a format pair the engine
+    # serves, no `coordinates:` / `preserve_hints` / compression knobs.
+    def convert_options?(options, path)
+      return false unless options.keys.all? { |key| CONVERT_OPTIONS.include?(key) }
+      return false unless options[:output].is_a?(String) || options[:output].respond_to?(:to_path)
+      return false unless timestamp_option?(options[:timestamp])
+
+      target = convert_target(options[:to]) or return false
+      return false unless path.is_a?(String)
+      return false if otc_hint?(path)
+
+      (collection_file?(path) ? COLLECTION_TARGETS : SINGLE_TARGETS).include?(target)
+    end
+
+    def convert_target(value)
+      return nil unless value.is_a?(Symbol) || value.is_a?(String)
+
+      target = value.to_s.downcase.to_sym
+      TARGET_CODES.key?(target) ? target : nil
+    end
+
+    def timestamp_option?(value)
+      value.nil? || value.is_a?(Integer) || value.respond_to?(:to_time)
+    end
+
+    def extract_options?(options)
+      options.keys.sort == %i[index output_dir] && options[:index].is_a?(Integer) &&
+        !options[:index].negative? && options[:output_dir].respond_to?(:to_str)
+    end
+
+    def instance_options?(options, path)
+      return false unless options.keys.all? { |key| %i[coords timestamp].include?(key) }
+      return false unless options[:coords].is_a?(Hash) && !path.nil? && !collection_file?(path)
+
+      options[:coords].all? { |tag, value| tag.to_s.bytesize == 4 && numeric?(value) }
+    end
+
+    def subset_options?(options, path)
+      return false unless options.keys.all? { |key| %i[unicodes text profile timestamp].include?(key) }
+      return false if path.nil? || collection_file?(path)
+      return false unless SUBSET_PROFILES.include?(options.fetch(:profile, "web"))
+
+      text = options[:text]
+      return false unless text.nil? || text.is_a?(String)
+
+      Array(options[:unicodes]).all? { |cp| cp.is_a?(Integer) && cp.between?(0, MAX_CODEPOINT) }
+    end
+
+    def numeric?(value)
+      Float(value)
+      true
+    rescue ArgumentError, TypeError
+      false
+    end
+
+    def finish_convert(path, target, output, bytes)
+      File.binwrite(output, bytes)
+      result = { success: true, input_path: path, output_path: output }
+      result.merge!(convert_formats(path, target))
+      result.merge(input_size: File.size(path), output_size: bytes.bytesize,
+                   **convert_tail(path))
+    end
+
+    def convert_formats(path, target)
+      return { source_format: single_format(path), target_format: target } unless collection_file?(path)
+
+      source = File.binread(path, 4) == "wOF2" ? :woff2_collection : :ttc
+      { source_format: source, target_format: target == :woff2 ? :woff2_collection : target }
+    end
+
+    # Collections report `num_fonts`; single fonts the variation strategy
+    # (an fvar font is converted as an instance, the rest are preserved).
+    def convert_tail(path)
+      return { num_fonts: collection_font_count(path) } if collection_file?(path)
+
+      { variation_strategy: variable_font?(path) ? :instance : :preserve }
+    end
+
+    def single_format(path)
+      FontLoader.detect_format(path)
+    end
+
+    # A WOFF2 collection is counted from its directory, not decoded: the
+    # decode needs `brotli`, which the java platform (JRuby) does not have, and
+    # the engine has already served the convert.
+    def collection_font_count(path)
+      if File.binread(path, 4) == "wOF2"
+        return Woff2::CollectionDecoder.new(File.binread(path)).font_count
+      end
+
+      FontLoader.load_collection(path).num_fonts
+    end
+
+    def variable_font?(path)
+      return woff2_tags(path).include?("fvar") if File.binread(path, 4) == "wOF2"
+
+      font = FontLoader.load(path, mode: :metadata, lazy: true)
+      font.has_table?("fvar")
+    ensure
+      font.close if font.respond_to?(:close)
+    end
+
+    # Table tags from the WOFF2 table directory, which is stored uncompressed
+    # (no `brotli` needed, unlike loading the font).
+    def woff2_tags(path)
+      File.open(path, "rb") do |io|
+        header = Woff2::Woff2Header.read(io)
+        Woff2Font.read_table_directory_from_io(io, header).map(&:tag)
+      end
+    end
+
+    def unix_seconds(timestamp)
+      timestamp.respond_to?(:to_time) ? timestamp.to_time.to_i : Integer(timestamp)
+    end
+
+    # Raise the Ruby tier's exception: class, message and the cause chain
+    # (each cause is raised so that its own #cause is set).
+    def raise_failure(details, byte_operation: false)
+      class_name, message, causes = details
+      cause = nil
+      causes.reverse_each { |name, text| cause = build_exception(name, text, cause) }
+      klass, message = byte_failure(class_name, message) if byte_operation
+      raise build_instance(klass || exception_class(class_name), message), cause: cause
+    end
+
+    # The Ruby class and message of a failed byte operation, so that a tier
+    # never changes what a caller can rescue or match: an engine error that
+    # names the Ruby exception it mirrors ("RuntimeError: ...") is unwrapped,
+    # and the engine's unrecognised-format error becomes the loader's.
+    def byte_failure(class_name, message)
+      if class_name == "Fontisan::Error" && (match = FAILURE_MESSAGE.match(message))
+        class_name = match[1]
+        message = match[2]
+      end
+      return [InvalidFontError, FontLoader::UNKNOWN_FORMAT_MESSAGE] if message == UNRECOGNISED_FORMAT_MESSAGE
+
+      [exception_class(class_name), message]
+    end
+
+    # `klass.new(message)`, or the `message:` keyword form some Fontisan
+    # errors use (MissingVariationTableError); never a failed constructor.
+    def build_instance(klass, message)
+      klass.new(message)
+    rescue ArgumentError
+      begin
+        klass.new(message: message)
+      rescue ArgumentError
+        Fontisan::Error.new(message)
+      end
+    end
+
+    def build_exception(name, text, cause)
+      raise build_instance(exception_class(name), text), cause: cause
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      e
+    end
+
+    def exception_class(name)
+      klass = Object.const_get(name)
+      klass.is_a?(Class) && klass <= Exception ? klass : Fontisan::Error
+    rescue NameError
+      Fontisan::Error
+    end
+  end
+end

data/lib/fontisan/cli.rb

@@ -226,7 +226,7 @@ module Fontisan
     # @param font_file [String] Path to the font file
     def subset(font_file)
       command = Commands::SubsetCommand.new(font_file, options)
-      result = command.run
+      result = command.run_routed
 
       unless options[:quiet]
         puts "Subset font created:"
@@ -422,7 +422,7 @@ module Fontisan
       convert_options[:options] = conv_options if conv_options
 
       command = Commands::ConvertCommand.new(font_file, convert_options)
-      command.run
+      command.run_routed
     rescue Errno::ENOENT, Error => e
       handle_error(e)
     end
@@ -443,7 +443,7 @@ module Fontisan
     option :opsz, type: :numeric,
                   desc: "Optical size axis value"
     option :named_instance, type: :string,
-                            desc: "Use named instance (e.g., 'Bold', 'Light')",
+                            desc: "Use named instance by fvar index (e.g., 0, 1; see --list-instances)",
                             aliases: "-n"
     option :list_instances, type: :boolean, default: false,
                             desc: "List available named instances",
@@ -463,7 +463,7 @@ module Fontisan
     #   fontisan instance variable.ttf --wght=700 --output=bold.ttf
     #
     # @example Use named instance
-    #   fontisan instance variable.ttf --named-instance="Bold" --output=bold.ttf
+    #   fontisan instance variable.ttf --named-instance=0 --output=bold.ttf
     #
     # @example Instance with format conversion
     #   fontisan instance variable.ttf --wght=700 --to=woff2 --output=bold.woff2
@@ -668,7 +668,7 @@ module Fontisan
     #   fontisan unpack family.ttc --output-dir extracted/ --prefix "NotoSans"
     def unpack(font_file)
       command = Commands::UnpackCommand.new(font_file, options)
-      result = command.run
+      result = command.run_routed
 
       unless options[:quiet]
         puts "Collection unpacked successfully:"

data/lib/fontisan/commands/audit_command.rb

@@ -103,9 +103,9 @@ module Fontisan
       # ------------------------------------------------------------------
 
       def populate_identity(report, face)
-        return unless face.has_table?(Constants::NAME_TAG)
+        name_table = readable_table(face, Constants::NAME_TAG)
+        return unless name_table
 
-        name_table = face.table(Constants::NAME_TAG)
         report.family_name = name_table.english_name(Tables::Name::FAMILY)
         report.subfamily_name = name_table.english_name(Tables::Name::SUBFAMILY)
         report.full_name = name_table.english_name(Tables::Name::FULL_NAME)
@@ -113,9 +113,17 @@ module Fontisan
           name_table.english_name(Tables::Name::POSTSCRIPT_NAME)
         report.version = name_table.english_name(Tables::Name::VERSION)
 
-        return unless face.has_table?(Constants::HEAD_TAG)
+        head = readable_table(face, Constants::HEAD_TAG)
+        report.font_revision = head.font_revision if head
+      end
 
-        report.font_revision = face.table(Constants::HEAD_TAG).font_revision
+      # A table listed in the directory whose data cannot be read (offset or
+      # length outside the file) comes back from `face.table` as nil. The
+      # audit reports on what is readable, so such a table is treated as
+      # absent: its section stays empty instead of raising NoMethodError on
+      # nil. The native tier does the same.
+      def readable_table(face, tag)
+        face.has_table?(tag) ? face.table(tag) : nil
       end
 
       # ------------------------------------------------------------------
@@ -126,13 +134,15 @@ module Fontisan
         report.is_variable = false
         report.italic = false
         report.bold = false
-        populate_os2_style(report, face) if face.has_table?(Constants::OS2_TAG)
-        populate_head_style(report, face) if face.has_table?(Constants::HEAD_TAG)
-        populate_fvar_style(report, face) if face.has_table?(Constants::FVAR_TAG)
+        populate_os2_style(report, face)
+        populate_head_style(report, face)
+        populate_fvar_style(report, face)
       end
 
       def populate_os2_style(report, face)
-        os2 = face.table(Constants::OS2_TAG)
+        os2 = readable_table(face, Constants::OS2_TAG)
+        return unless os2
+
         report.weight_class = os2.us_weight_class
         report.width_class = os2.us_width_class
         report.italic = os2.fs_selection && (os2.fs_selection & 0x01).positive?
@@ -141,7 +151,9 @@ module Fontisan
       end
 
       def populate_head_style(report, face)
-        head = face.table(Constants::HEAD_TAG)
+        head = readable_table(face, Constants::HEAD_TAG)
+        return unless head
+
         mac_style = head.mac_style || 0
         # head macStyle overrides OS/2 fsSelection only when OS/2 didn't set it
         report.italic = true if (mac_style & 0x02).positive?
@@ -149,8 +161,10 @@ module Fontisan
       end
 
       def populate_fvar_style(report, face)
+        fvar = readable_table(face, Constants::FVAR_TAG)
+        return unless fvar
+
         report.is_variable = true
-        fvar = face.table(Constants::FVAR_TAG)
         report.axes = fvar.axes.map do |axis|
           Models::AuditAxis.new(
             tag: axis.axis_tag,
@@ -173,8 +187,8 @@ module Fontisan
       # ------------------------------------------------------------------
 
       def populate_coverage(report, face)
-        if face.has_table?(Constants::CMAP_TAG)
-          cmap = face.table(Constants::CMAP_TAG)
+        cmap = readable_table(face, Constants::CMAP_TAG)
+        if cmap
           mappings = cmap.unicode_mappings || {}
           report.total_codepoints = mappings.size
           report.cmap_subtables = cmap.subtable_formats
@@ -208,48 +222,29 @@ module Fontisan
       # OpenType layout (GSUB/GPOS)
       # ------------------------------------------------------------------
 
+      # GSUB and GPOS are each read once through the budgeted
+      # `script_features`, which serves both the scripts and their features.
       def populate_layout(report, face)
-        report.opentype_scripts = collect_scripts(face)
-        report.features = collect_features(face)
-      end
-
-      def collect_scripts(face)
         scripts = Set.new
-        %w[GSUB GPOS].each do |tag|
-          next unless face.has_table?(tag)
-
-          table = face.table(tag)
-          scripts.merge(table.scripts) if table
-        end
-        scripts.sort
-      end
-
-      def collect_features(face)
         features = Set.new
         %w[GSUB GPOS].each do |tag|
           next unless face.has_table?(tag)
 
           table = face.table(tag)
-          features.merge(collect_features_from_table(table)) if table
-        end
-        features.sort
-      end
+          next unless table
 
-      def collect_features_from_table(layout_table)
-        scripts = begin
-                    layout_table.scripts
-        rescue StandardError
-                    []
+          scripts.merge(table.scripts)
+          table.script_features.each_value { |tags| features.merge(tags) }
         end
-        scripts.flat_map { |script| features_for_script(layout_table, script) }
-      rescue StandardError
-        []
+        report.opentype_scripts = printable_tags(scripts.sort)
+        report.features = printable_tags(features.sort)
       end
 
-      def features_for_script(layout_table, script)
-          layout_table.features(script_tag: script)
-      rescue StandardError
-          []
+      # Layout tags come from BinData as ASCII-8BIT. A damaged table can yield
+      # bytes that are not UTF-8, which the JSON generator rejects. Each
+      # invalid byte becomes U+FFFD, as the native tier's lossy decode does.
+      def printable_tags(tags)
+        tags.map { |tag| tag.dup.force_encoding(Encoding::UTF_8).scrub }
       end
 
       # ------------------------------------------------------------------

data/lib/fontisan/commands/convert_command.rb

@@ -64,10 +64,13 @@ module Fontisan
       # @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 [Integer] :timestamp Fixed head.modified (Unix seconds)
+      #   for WOFF2 output; nil (default) stamps the current time
       # @option options [Boolean] :no_validate Skip output validation
       # @option options [Boolean] :verbose Verbose output
       # @option options [ConversionOptions] :options ConversionOptions object
       def initialize(font_path, options = {})
+        check_sfnt_directory!(font_path)
         super(font_path, options)
 
         # Convert string keys to symbols for Thor compatibility. All command
@@ -134,8 +137,57 @@ module Fontisan
         raise Error, "Conversion failed: #{e.message}"
       end
 
+      # Execute through the engine selection (the CLI entry): a tier other than
+      # Ruby serves the plain single-target conversions it supports, anything
+      # else (several targets, instance coordinates, ConversionOptions, hints,
+      # collection target format, compression knobs, a font index) runs {#run}
+      # on the Ruby tier. A routed conversion prints the same summary lines
+      # (minus the variation note) unless +quiet+.
+      #
+      # @return [Hash] same as {#run} for a single target
+      def run_routed
+        validate_options!
+        gate = routed_options
+        return run unless gate && Engine.resolve(:convert, font_path.to_s, gate) != :ruby
+
+        result = Reference.convert(font_path, **gate)
+        print_routed_summary(result) unless @options[:quiet]
+        result
+      end
+
       private
 
+      # A plain sfnt whose table directory the engine tiers reject fails with
+      # their error, before the loader can raise its own (fontist/fontisan#159).
+      def check_sfnt_directory!(path)
+        path = path.to_path if path.respond_to?(:to_path)
+        return unless path.is_a?(String) && File.file?(path)
+        return unless %i[ttf otf].include?(FontLoader.detect_format(path))
+
+        SfntDirectory.check!(File.binread(path))
+      rescue SfntDirectory::Malformed => e
+        raise Error, "Conversion failed: #{e.message}"
+      end
+
+      # Reference.convert keywords when the call is a plain conversion; else nil.
+      def routed_options
+        return nil if multi_format? || @coordinates || @instance_index || @conv_options
+        return nil if @preserve_hints || !@preserve_variation.nil? || @collection_target_format != "preserve"
+        return nil if @options.fetch(:font_index, 0).to_i != 0
+        return nil if Converters::FormatConverter.all_strategy_option_names.any? { |name| @options.key?(name) }
+        return nil unless @output_path.is_a?(String)
+
+        { to: @target_formats.first, output: @output_path }
+      end
+
+      def print_routed_summary(result)
+        puts "Converting #{File.basename(font_path)} to #{result[:target_format]}..."
+        puts "Conversion complete!"
+        puts "  Input:  #{font_path} (#{format_size(result[:input_size])})"
+        puts "  Output: #{result[:output_path]} (#{format_size(result[:output_size])})"
+        puts "  Format: #{result[:source_format]} → #{result[:target_format]}"
+      end
+
       # @return [Boolean] true when more than one target format was given
       def multi_format?
         @target_formats.size > 1
@@ -268,6 +320,7 @@ module Fontisan
             output: @output_path,
             target_format: @collection_target_format,
             verbose: @options[:verbose],
+            timestamp: @options[:timestamp],
             options: @conv_options, # Pass ConversionOptions
           },
         )

data/lib/fontisan/commands/instance_command.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "thor"
 
 module Fontisan
@@ -27,10 +28,27 @@ module Fontisan
     # @example Dry-run to preview
     #   fontisan instance variable.ttf --wght=700 --dry-run
     class InstanceCommand < BaseCommand
+      # Options that make an instance request more than plain axis coordinates.
+      NON_PLAIN_OPTIONS = %i[validate list_instances dry_run named_instance
+                             to optimize progress].freeze
+      TRUETYPE_MAGIC = "\x00\x01\x00\x00".b.freeze
+
+      # The CLI builds the command bare and hands the font to {#execute}, so
+      # the font is not loaded here (BaseCommand's constructor loads one).
+      #
+      # @param font_path [String, nil] unused until {#execute}
+      # @param options [Hash] command options
+      def initialize(font_path = nil, options = {}) # rubocop:disable Lint/MissingSuper
+        @font_path = font_path
+        @options = options
+      end
+
       # Instance a variable font at specified coordinates
       #
       # @param input_path [String] Path to variable font file
       def execute(input_path, options = {})
+        return if write_routed(input_path, options)
+
         # Load variable font
         font = load_font(input_path)
 
@@ -72,6 +90,34 @@ module Fontisan
 
       private
 
+      # Serve a plain request (axis coordinates, the font's own format, a
+      # TrueType-outline sfnt) through the engine selection. Named instances,
+      # listing, dry-run, validation, --to, --optimize, --progress, CFF2 or
+      # wrapped inputs stay on the Ruby path in {#execute}. The Ruby writer and
+      # {Reference.instance} produce identical bytes for these requests.
+      #
+      # @return [String, nil] the output path when a non-Ruby tier wrote the
+      #   instance; nil when {#execute} must run the Ruby path
+      def write_routed(input_path, options)
+        gate = routed_gate(input_path, options)
+        return nil unless gate && Engine.resolve(:instance, input_path.to_s, gate) != :ruby
+
+        output_path = determine_output_path(input_path, options)
+        FileUtils.mkdir_p(File.dirname(output_path))
+        File.binwrite(output_path, Reference.instance(input_path, **gate))
+        puts "Static font instance written to: #{output_path}"
+        output_path
+      end
+
+      # Reference.instance keywords for a plain request; nil otherwise.
+      def routed_gate(input_path, options)
+        return nil if NON_PLAIN_OPTIONS.any? { |key| options[key] }
+        return nil unless File.file?(input_path) && File.binread(input_path, 4) == TRUETYPE_MAGIC
+
+        coords = extract_coordinates(options)
+        coords.empty? ? nil : { coords: coords }
+      end
+
       # Validate font before generating instance
       #
       # @param font [Object] Font object
@@ -164,6 +210,8 @@ module Fontisan
       # @param output_path [String] Output file path
       # @param options [Hash] Command options
       def instance_named(font, instance_index, output_path, options)
+        instance_index = parse_instance_index(instance_index, font)
+
         # Generate instance using named instance
         generator = Variation::InstanceGenerator.new(font)
         tables = generator.generate_named_instance(instance_index)
@@ -181,6 +229,33 @@ module Fontisan
         )
       end
 
+      # Convert the --named-instance value (a string from Thor) to a valid
+      # fvar instance index. The generator takes an Integer, so the conversion
+      # and range check live here, at the command boundary.
+      #
+      # @param value [String, Integer] raw option value
+      # @param font [Object] Font object
+      # @return [Integer] index into the fvar named instances
+      # @raise [ArgumentError] when not a non-negative integer or out of range
+      def parse_instance_index(value, font)
+        index = begin
+          Integer(value.to_s, 10)
+        rescue ArgumentError
+          raise ArgumentError,
+                "--named-instance must be an integer index, got #{value.inspect}"
+        end
+        raise ArgumentError, "--named-instance must be >= 0, got #{index}" if index.negative?
+
+        fvar = font.table("fvar") if font.respond_to?(:table)
+        count = fvar&.instances&.length
+        if count && index >= count
+          raise ArgumentError,
+                "--named-instance #{index} out of range (font has #{count} named instances)"
+        end
+
+        index
+      end
+
       # List available named instances
       #
       # @param font [Object] Font object

data/lib/fontisan/commands/subset_command.rb

@@ -33,6 +33,8 @@ module Fontisan
     #   )
     #   command.run
     class SubsetCommand < BaseCommand
+      ROUTED_PROFILES = %w[pdf web minimal].freeze
+
       # Initialize subset command
       #
       # @param font_path [String] Path to input font file
@@ -86,8 +88,49 @@ module Fontisan
               "Subsetting failed: #{e.message}"
       end
 
+      # Execute through the engine selection (the CLI entry): a tier other
+      # than Ruby subsets by text or Unicode codepoints with a profile the
+      # engine knows, and writes the bytes {#run} writes. Glyph-id input,
+      # retained GIDs, dropped hints or names, disabled Unicode-range pruning
+      # and verbose output run {#run} on the Ruby tier.
+      #
+      # @return [Hash] same as {#run}
+      def run_routed
+        gate = routed_gate
+        return run unless gate && Engine.resolve(:subset, font_path.to_s, gate) != :ruby
+
+        determine_glyph_ids # same errors as the Ruby path when nothing matches
+        bytes = Reference.subset(font_path, **gate)
+        FileUtils.mkdir_p(File.dirname(@output_path))
+        File.binwrite(@output_path, bytes)
+        routed_result(bytes, gate[:profile])
+      end
+
       private
 
+      # Reference.subset keywords for a plain request; nil otherwise.
+      def routed_gate
+        profile = options[:profile] || "pdf"
+        return nil if options[:glyphs] || options[:retain_gids] || options[:drop_hints] ||
+          options[:drop_names] || options[:unicode_ranges] == false || options[:verbose]
+        return nil unless ROUTED_PROFILES.include?(profile)
+
+        input = options[:text] ? { text: options[:text] } : { unicodes: parse_unicode(options[:unicode]) }
+        input.merge(profile: profile)
+      end
+
+      def routed_result(bytes, profile)
+        subset = FontLoader.load(@output_path)
+        {
+          input: font_path,
+          output: @output_path,
+          original_glyphs: font.table("maxp").num_glyphs,
+          subset_glyphs: subset.table("maxp").num_glyphs,
+          profile: profile,
+          size: bytes.bytesize,
+        }
+      end
+
       # Validate command options
       #
       # @raise [ArgumentError] If options are invalid