fontisan 0.4.47 → 0.4.48

data/lib/fontisan/ffi.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "tmpdir"
+require "rbconfig"
+require "fontisan/ffi_platform"
+
+module Fontisan
+  # The `:ffi` engine tier: the Rust engine's C ABI (fontisan.h, version 1)
+  # loaded through the optional `ffi` gem. It serves the read-side
+  # {Fontisan::Reference} operations (read, audit, audit_dir, scan) and the
+  # byte operations (convert, extract, instance, subset: card 2f-ffi, the same
+  # routing rules as {Fontisan::Native} through {Fontisan::ByteOps}); every
+  # other operation, and dfont / Type 1 files, are the Ruby tier's.
+  #
+  # The C ABI has no glyph-id operation: a subset's glyph ids come from the
+  # Ruby facade's `glyph_ids` (a pure cmap read, run on the Ruby tier).
+  #
+  # The `ffi` gem and the shared library are loaded lazily, on the first probe.
+  # A missing gem, missing or unloadable library, missing symbol or ABI
+  # mismatch makes {.available?} false and never raises.
+  #
+  # The library is looked up in FONTISAN_CDYLIB (a file path), then in
+  # lib/fontisan/ffi/<platform>/ (the java-platform gem, one directory per
+  # bundled OS and architecture, see {FfiPlatform}), then in lib/fontisan/ffi/
+  # (the platform gems).
+  #
+  # Tier contract: `available?`, `supports?(operation, path)` and
+  # `call(operation, *args, **kwargs)`, as for {Fontisan::Native}.
+  module Ffi
+    class AbiMismatch < Fontisan::Error; end
+
+    LIBRARY = "fontisan_cdylib"
+    OPERATIONS = %i[read audit audit_dir scan convert extract instance subset].freeze
+    RUBY_ONLY_FORMATS = %i[dfont pfa pfb].freeze
+
+    OP_CONVERT = 1
+    OP_EXTRACT = 2
+    OP_SUBSET = 6
+    OP_INSTANCE = 7
+    OP_READ = 8
+    OP_AUDIT = 9
+    OP_SCAN = 10
+    OP_AUDIT_DIR = 11
+    FLAG_METADATA = 1
+    FLAG_LAZY = 2
+    FLAG_VALIDATE = 1
+
+    CONVERT_FAILED = 8
+    SUBSET_PROFILE_CODES = { "pdf" => 0, "web" => 1, "minimal" => 2 }.freeze
+    FIXED_ONE = 65_536
+
+    class << self
+      include ByteOps
+
+      # Probe: true only when the `ffi` gem and a compatible library both load.
+      def available?
+        return @available if defined?(@available)
+
+        @available = probe
+      end
+
+      # Forget the memoised probe and the loaded library.
+      def reset!
+        @client = nil
+        remove_instance_variable(:@available) if defined?(@available)
+      end
+
+      # Whether this tier serves +operation+ for +path+: the read-side
+      # operations on anything but dfont and Type 1 files.
+      def supports?(operation, path = nil)
+        return false unless available? && OPERATIONS.include?(operation)
+
+        case operation
+        when *ByteOps::BYTE_OPERATIONS then path.is_a?(String) && File.file?(path) && !ruby_only?(path)
+        when :audit_dir then path.nil? || File.directory?(path)
+        when :scan then path.nil? || File.file?(path) && !ruby_only?(path)
+        else path.nil? || File.file?(path) && !ruby_only?(path)
+        end
+      end
+
+      # Options the engine honours; anything else is served by Ruby. The
+      # read-side operations check their own options and fall back inside.
+      def supports_options?(operation, options, path = nil)
+        return byte_options?(operation, options, path) if ByteOps::BYTE_OPERATIONS.include?(operation)
+
+        OPERATIONS.include?(operation)
+      end
+
+      def call(operation, *, **)
+        raise Fontisan::Error, "ffi tier cannot serve #{operation}" unless OPERATIONS.include?(operation)
+        raise Fontisan::Error, "ffi tier cannot serve #{operation}: library not loaded" unless available?
+
+        __send__(:"serve_#{operation}", *, **)
+      end
+
+      private
+
+      attr_reader :client
+
+      def probe
+        require "fontisan/ffi/client"
+        path = library_path or return false
+        @client = Client.new(path)
+        true
+      rescue StandardError, ScriptError
+        @client = nil
+        false
+      end
+
+      def library_path
+        override = ENV.fetch("FONTISAN_CDYLIB", "").strip
+        return override unless override.empty?
+
+        extension = case RbConfig::CONFIG["host_os"]
+                    when /darwin/ then "dylib"
+                    when /mswin|mingw|cygwin/ then "dll"
+                    else "so"
+                    end
+        prefix = extension == "dll" ? "" : "lib"
+        file = "#{prefix}#{LIBRARY}.#{extension}"
+        platform = FfiPlatform.dir
+        bundled = platform && File.expand_path("ffi/#{platform}/#{file}", __dir__)
+        bundled && File.file?(bundled) ? bundled : File.expand_path("ffi/#{file}", __dir__)
+      end
+
+      def ruby_only?(path)
+        RUBY_ONLY_FORMATS.include?(FontLoader.detect_format(path))
+      rescue StandardError
+        false
+      end
+
+      # Writes the converted font to +output+; returns the ConvertCommand hash.
+      def serve_convert(path, output:, timestamp: nil, **options)
+        path = File.path(path)
+        target = convert_target(options.fetch(:to))
+        stamp = timestamp ? unix_seconds(timestamp) : Time.now.to_i
+        prefix = [ByteOps::TARGET_CODES.fetch(target), 0, stamp].pack("NNq>")
+        bytes = byte_op(OP_CONVERT, prefix + File.binread(path))
+        finish_convert(path, target, File.path(output), bytes)
+      end
+
+      # Same file layout as UnpackCommand: <output_dir>/<basename>.
+      def serve_extract(path, index:, output_dir:)
+        payload = byte_op(OP_EXTRACT, [index, 0, 0, 0].pack("NNNN") + File.binread(File.path(path)))
+        length = payload.unpack1("N")
+        name = payload.byteslice(4, length).force_encoding(Encoding::UTF_8)
+        FileUtils.mkdir_p(output_dir)
+        File.join(output_dir, name).tap { |out| File.binwrite(out, payload.byteslice(4 + length..)) }
+      end
+
+      def serve_instance(path, coords:, timestamp: nil)
+        _ = timestamp
+        axes = coords.map { |tag, value| tag.to_s.b + [(Float(value) * FIXED_ONE).round].pack("l>") }
+        byte_op(OP_INSTANCE, [axes.size].pack("N") + axes.join + File.binread(File.path(path)))
+      end
+
+      def serve_subset(path, unicodes: nil, text: nil, profile: "web", timestamp: nil)
+        _ = timestamp
+        path = File.path(path)
+        gids = subset_glyph_ids(path, unicodes, text)
+        head = [SUBSET_PROFILE_CODES.fetch(profile.to_s), gids.size, 0, 0].pack("NNNN")
+        byte_op(OP_SUBSET, head + gids.pack("N*") + File.binread(path))
+      end
+
+      # Glyph ids of a subset request. A WOFF2 source on a platform without the
+      # `brotli` gem (the java gem on JRuby) cannot be read by the Ruby tier, so
+      # the engine decodes it (a convert to the same flavor) and the Ruby tier
+      # reads the cmap of that SFNT, under the source's own basename.
+      def subset_glyph_ids(path, unicodes, text)
+        return ruby(:glyph_ids, path, unicodes: unicodes, text: text) unless woff2_without_brotli?(path)
+
+        Dir.mktmpdir("fontisan-ffi-subset") do |dir|
+          decoded = File.join(dir, File.basename(path))
+          File.binwrite(decoded, decode_woff2(path))
+          ruby(:glyph_ids, decoded, unicodes: unicodes, text: text)
+        end
+      end
+
+      def woff2_without_brotli?(path)
+        File.binread(path, 4) == "wOF2" && !Utilities::BrotliWrapper.available?
+      end
+
+      def decode_woff2(path)
+        input = File.binread(path)
+        target = input.byteslice(4, 4) == "OTTO" ? :otf : :ttf
+        byte_op(OP_CONVERT, [ByteOps::TARGET_CODES.fetch(target), 0, 0].pack("NNq>") + input)
+      end
+
+      # The payload of a byte operation; a failure is raised as the Ruby
+      # exception the message names (the ABI carries no cause chain).
+      def byte_op(operation, input)
+        reply = client.call(operation, input)
+        return reply.payload if reply.status == Client::OK
+
+        raise_byte_failure(reply)
+      end
+
+      def raise_byte_failure(reply)
+        match = ByteOps::FAILURE_MESSAGE.match(reply.message)
+        if reply.status == CONVERT_FAILED && match
+          klass, message = byte_failure(match[1], match[2])
+          raise build_instance(klass, message)
+        end
+
+        raise Fontisan::Error, "fontisan ffi status #{reply.status}: #{reply.message}"
+      end
+
+      def serve_read(path, mode: :metadata, lazy: true)
+        return ruby(:read, path, mode: mode, lazy: lazy) unless %i[metadata full].include?(mode)
+
+        path = reference_path(path)
+        flags = (mode == :metadata ? FLAG_METADATA : 0) | (lazy ? FLAG_LAZY : 0)
+        reply = client.call(OP_READ, File.binread(path), flags)
+        return ruby(:read, path, mode: mode, lazy: lazy) if reply.status == Client::UNSUPPORTED
+
+        rows(reply)
+      end
+
+      def serve_audit(path, validate: false)
+        return ruby(:audit, path, validate: validate) unless [true, false, nil].include?(validate)
+
+        path = reference_path(path)
+        input = [File.basename(path).bytesize].pack("N") + File.basename(path).b + File.binread(path)
+        reply = client.call(OP_AUDIT, input, validate ? FLAG_VALIDATE : 0)
+        return ruby(:audit, path, validate: validate) if reply.status == Client::UNSUPPORTED
+
+        rows(reply)
+      end
+
+      def serve_scan(paths)
+        Array(paths).flat_map do |path|
+          reply = client.call(OP_SCAN, File.path(path))
+          result = reply.status == Client::OK ? decode(reply.payload) : nil
+          result = nil if result&.any? { |row| row["status"] == "unsupported" }
+          # "status" is the engine's routing marker; Reference rows have none.
+          result ? result.map { |row| row.except("status") } : ruby(:scan, [path])
+        end
+      end
+
+      def serve_audit_dir(dir, validate: false)
+        return ruby(:audit_dir, dir, validate: validate) unless [true, false, nil].include?(validate)
+
+        dir = reference_path(dir)
+        reply = client.call(OP_AUDIT_DIR, dir, validate ? FLAG_VALIDATE : 0)
+        raise Fontisan::Error, reply.message unless reply.status == Client::OK
+
+        decode(reply.payload).filter_map { |row| dir_entry(dir, row, validate) }
+      end
+
+      def dir_entry(dir, row, validate)
+        rel = Reference.relative_row_path(dir, row["path"])
+        # Like the Ruby and native tiers: nothing below a hidden directory.
+        return if rel.split("/").any? { |part| part.start_with?(".") }
+
+        seen_by(File.join(dir, rel), :ffi)
+        case row["status"]
+        when "ok" then { "path" => rel, "faces" => row["reports"] }
+        when "error" then { "path" => rel, "error" => row["error"].slice("class", "message") }
+        else ruby_entry(dir, rel, validate)
+        end
+      end
+
+      # A file the engine does not read (dfont, Type 1): the Ruby tier audits it.
+      def ruby_entry(dir, rel, validate)
+        file = File.join(dir, rel)
+        seen_by(file, :ruby)
+        { "path" => rel, "faces" => Reference.normalize(Engine.ruby_call(:audit, file, validate: validate)) }
+      rescue StandardError => e
+        { "path" => rel, "error" => { "class" => e.class.name, "message" => e.message } }
+      end
+
+      def seen_by(file, tier)
+        recorder = Thread.current[Engine::ROW_RECORDER]
+        recorder[file] = tier if recorder
+      end
+
+      def reference_path(path)
+        Reference.__send__(:path_arg, path)
+      end
+
+      def ruby(operation, ...)
+        Engine.ruby_call(operation, ...)
+      end
+
+      # The rows of a successful read/audit reply, or the Ruby exception the
+      # engine reports for a failed one.
+      def rows(reply)
+        case reply.status
+        when Client::OK then decode(reply.payload)
+        when Client::READ_FAILED then raise_reported(JSON.parse(reply.message))
+        else raise Fontisan::Error, "fontisan ffi status #{reply.status}: #{reply.message}"
+        end
+      end
+
+      # Packed rows: u32 BE count, then per row u32 BE length + UTF-8 JSON.
+      def decode(payload)
+        count, = payload.unpack("N")
+        offset = 4
+        Array.new(count) do
+          length = payload.byteslice(offset, 4).unpack1("N")
+          row = JSON.parse(payload.byteslice(offset + 4, length))
+          offset += 4 + length
+          row
+        end
+      end
+
+      # Raise the reported error as its Ruby class, message and cause chain.
+      def raise_reported(report)
+        raise_chain([report.slice("class", "message"),
+                     *Array(report["causes"])])
+      end
+
+      def raise_chain(infos)
+        info, *rest = infos
+        return raise(build_error(info)) if rest.empty?
+
+        begin
+          raise_chain(rest)
+        rescue StandardError => e
+          raise build_error(info), cause: e
+        end
+      end
+
+      def build_error(info)
+        klass = begin
+          Object.const_get(info["class"])
+        rescue NameError
+          nil
+        end
+        return Fontisan::Error.new("#{info['class']}: #{info['message']}") unless klass.is_a?(Class) && klass <= StandardError
+
+        error = klass.new(info["message"])
+        return error if error.message == info["message"]
+
+        # Errno classes prefix their text; the report already carries it whole.
+        error.define_singleton_method(:message) { info["message"] }
+        error
+      end
+    end
+  end
+end

data/lib/fontisan/ffi_platform.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Fontisan
+  # Names the per-platform directory under lib/fontisan/ffi/ that holds a
+  # cdylib in the `java`-platform gem. That gem is one artefact for every OS,
+  # so the library cannot sit at one flat path the way it does in a platform
+  # gem (two macOS architectures would collide). Shared by {Fontisan::Ffi}
+  # and rakelib/java.rake.
+  module FfiPlatform
+    DIRS = %w[linux-x86_64 darwin-arm64 darwin-x86_64 windows-x86_64].freeze
+
+    # @return [String, nil] one of {DIRS}, nil for an unbundled platform
+    def self.dir(host_os = RbConfig::CONFIG["host_os"], host_cpu = RbConfig::CONFIG["host_cpu"])
+      os = case host_os
+           when /darwin/ then "darwin"
+           when /mswin|mingw|cygwin|windows/ then "windows"
+           when /linux/ then "linux"
+           end
+      cpu = host_cpu.to_s.match?(/arm64|aarch64/) ? "arm64" : "x86_64"
+      candidate = "#{os}-#{cpu}"
+      DIRS.include?(candidate) ? candidate : nil
+    end
+  end
+end

data/lib/fontisan/font_loader.rb

@@ -31,6 +31,10 @@ module Fontisan
   #   font = FontLoader.load("font.ttf", lazy: true)   # Tables loaded on-demand
   #   font = FontLoader.load("font.ttf", lazy: false)  # All tables loaded upfront
   class FontLoader
+    # The one text every tier raises for a file that is no font at all.
+    UNKNOWN_FORMAT_MESSAGE =
+      "Unknown font format. Expected TTF, OTF, TTC, OTC, WOFF, WOFF2, PFB, or PFA file."
+
     # Number of bytes read from the start of a file to identify its format.
     # 100 bytes is enough to comfortably contain the Adobe Type 1 PFA header
     # plus its leading whitespace, and far more than the 4 bytes needed for
@@ -91,7 +95,7 @@ module Fontisan
       when :pfa, :pfb then Type1Font.from_file(path, mode: resolved_mode)
       else
         raise InvalidFontError,
-              "Unknown font format. Expected TTF, OTF, TTC, OTC, WOFF, WOFF2, PFB, or PFA file."
+              UNKNOWN_FORMAT_MESSAGE
       end
     end
 

data/lib/fontisan/font_writer.rb

@@ -162,7 +162,7 @@ module Fontisan
 
       tags.each do |tag|
         data = @tables[tag]
-        checksum = calculate_table_checksum(data)
+        checksum = calculate_table_checksum(directory_checksum_source(tag, data))
 
         # Calculate padding to 4-byte boundary
         padding_length = Utilities::Padding.boundary(data.bytesize)
@@ -227,6 +227,18 @@ module Fontisan
       ].pack("a4 N N N")
     end
 
+    # The bytes a table's directory checksum is computed over. The OpenType
+    # spec computes the head checksum with checkSumAdjustment (offset 8) as
+    # zero; using the source font's value made write -> reload -> write
+    # produce different bytes.
+    def directory_checksum_source(tag, data)
+      return data unless tag == "head" && data.bytesize >= 12
+
+      zeroed = data.b
+      zeroed[8, 4] = "\x00\x00\x00\x00".b
+      zeroed
+    end
+
     # Calculate checksum for a table
     #
     # The checksum is calculated by summing all uint32 values in the table.

data/lib/fontisan/native.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Fontisan
+  # The `:native` engine tier: the fontisan-rs engine through a magnus
+  # extension (`ext/fontisan_native`, built by rb-sys).
+  #
+  # Tier contract (see {Fontisan::Engine}): `available?`,
+  # `supports?(operation, path)`, `supports_options?(operation, kwargs)` and
+  # `call(operation, *args, **kwargs)`.
+  #
+  # The extension returns the same Hash / Array / String shapes as
+  # {Fontisan::Reference}: it walks the engine's documents straight into Ruby
+  # objects (no JSON text on either side), with the GVL released around each
+  # engine call. A failure arrives as {Failure}; {.call} rebuilds the Ruby
+  # tier's exception class, message and cause chain from it.
+  module Native
+    EXTENSION = "fontisan/native/fontisan_native"
+    # Cross-compiled platform gems ship one build per Ruby minor, in a
+    # directory named for it (rake-compiler's fat-binary layout).
+    VERSIONED_EXTENSION = "fontisan/native/#{RUBY_VERSION[/\A\d+\.\d+/]}/fontisan_native".freeze
+    ABI_VERSION = 1
+
+    # The fontisan-rs commit both binaries must be built from: the `rev` of the
+    # engine pin in ext/*/Cargo.toml, which each build embeds. ABI_VERSION does
+    # not move on a repin, so this is what keeps a stale binary from serving old
+    # behaviour. A repin seds it with the Cargo files (repin-push162.sh).
+    ENGINE_REV = "daffb3f45b67517e924a3e5d0e113a2ecbde9959"
+
+    # Operations served natively. Convert, extract, instance and subset are
+    # path-based only (card 2f): the object-based entry points
+    # (`Subset::Builder.new(font, ...)`, `Variable::Instancer.new(font)`) are
+    # not Reference operations, so they never reach a gate and stay on Ruby.
+    OPERATIONS = %i[read audit audit_dir scan convert extract instance subset].freeze
+
+    # Raised by the extension for an engine failure; `details` is
+    # `[class name, message, [[cause class, cause message], ...]]`.
+    class Failure < StandardError
+      attr_reader :details
+    end
+
+    # A Rust panic, caught in the extension and surfaced as a Ruby error.
+    class Panic < Fontisan::Error; end
+
+    class << self
+      include ByteOps
+
+      # Probe: true only when the extension loads and reports the ABI this
+      # gem expects. Any load failure (missing library, missing symbol, ABI
+      # mismatch, a broken loader) is a plain false, never an exception.
+      def available?
+        return @available if defined?(@available)
+
+        @available = probe.tap { |ok| warn_unusable unless ok }
+      end
+
+      # Forget the memoised probe (tests, or after installing the extension).
+      def reset!
+        remove_instance_variable(:@available) if defined?(@available)
+      end
+
+      # @return [Boolean] whether the extension serves +operation+ for +path+.
+      #   dfont and Type 1 files, missing files and non-directories (for
+      #   audit_dir) stay with the Ruby tier.
+      def supports?(operation, path = nil)
+        return false unless available? && OPERATIONS.include?(operation)
+        return false unless path.is_a?(String)
+
+        case operation
+        when :audit_dir then File.directory?(path)
+        # A FIFO, device or socket is never handed to the extension: it would
+        # block in the engine's read with the GVL released, where no signal or
+        # Timeout can interrupt it. Ruby's read is interruptible.
+        else File.file?(path) && native_supports_file(path)
+        end
+      end
+
+      # Options the extension honours; anything else is served by Ruby.
+      # +path+ is the call's input path (the Engine passes it when this method
+      # takes a third argument): collection inputs and the `.otc` hint decide
+      # some of the byte ops.
+      def supports_options?(operation, options, path = nil)
+        case operation
+        when :read then read_options?(options)
+        when *ByteOps::BYTE_OPERATIONS then byte_options?(operation, options, path)
+        when :audit, :audit_dir then options.keys.all?(:validate) && [true, false, nil].include?(options[:validate])
+        when :scan then options.empty?
+        else false
+        end
+      end
+
+      def call(operation, *, **)
+        case operation
+        when :read then read(*, **)
+        when :audit then audit(*, **)
+        when :audit_dir then audit_dir(*, **)
+        when :scan then scan(*)
+        when :convert then convert(*, **)
+        when :extract then extract(*, **)
+        when :instance then instance(*, **)
+        when :subset then subset(*, **)
+        else raise Fontisan::Error, "native tier cannot serve #{operation}"
+        end
+      rescue Failure => e
+        raise_failure(e.details, byte_operation: ByteOps::BYTE_OPERATIONS.include?(operation))
+      end
+
+      private
+
+      def probe
+        load_extension
+        abi_version == ABI_VERSION && engine_rev == ENGINE_REV
+      rescue StandardError, ScriptError
+        false
+      end
+
+      # An extension file that is shipped but does not load or report the
+      # expected ABI leaves every call on the Ruby tier. Say so once; the
+      # fallback itself is unchanged. No file at all (a source install without
+      # cargo) is the normal :ruby gem and stays quiet.
+      def warn_unusable
+        return if @warned_unusable || !extension_present?
+
+        @warned_unusable = true
+        warn "fontisan: the native extension is present but did not load (or has the wrong ABI " \
+             "or was built from another engine rev); " \
+             "falling back to the Ruby tier. Reinstall the gem or run `bundle exec rake compile`."
+      end
+
+      def extension_present?
+        [VERSIONED_EXTENSION, EXTENSION].any? { |feature| $LOAD_PATH.resolve_feature_path(feature) }
+      end
+
+      def load_extension
+        require VERSIONED_EXTENSION
+      rescue LoadError
+        require EXTENSION
+      end
+
+      def abi_version
+        respond_to?(:extension_abi_version) ? extension_abi_version : nil
+      end
+
+      def engine_rev
+        respond_to?(:extension_engine_rev) ? extension_engine_rev : nil
+      end
+
+      def read_options?(options)
+        return false unless options.keys.all? { |key| %i[mode lazy].include?(key) }
+
+        %w[metadata full].include?(options.fetch(:mode, :metadata).to_s) &&
+          [true, false].include?(options.fetch(:lazy, true))
+      end
+
+      # Writes the converted font to +output+ and returns the ConvertCommand
+      # result hash, rebuilt from the engine's bytes and the input header.
+      def convert(path, output:, timestamp: nil, **options)
+        path = File.path(path)
+        target = convert_target(options.fetch(:to))
+        bytes = native_convert(path, ByteOps::TARGET_CODES.fetch(target), timestamp ? unix_seconds(timestamp) : Time.now.to_i)
+        finish_convert(path, target, File.path(output), bytes)
+      end
+
+      # Same file layout as UnpackCommand: <output_dir>/<basename>.
+      def extract(path, index:, output_dir:)
+        name, bytes = native_extract(File.path(path), index)
+        FileUtils.mkdir_p(output_dir)
+        File.join(output_dir, name).tap { |out| File.binwrite(out, bytes) }
+      end
+
+      def instance(path, coords:, timestamp: nil)
+        _ = timestamp
+        values = coords.to_h { |tag, value| [tag.to_s, Float(value)] }
+        native_instance(File.path(path), values.to_a)
+      end
+
+      def subset(path, unicodes: nil, text: nil, profile: "web", timestamp: nil)
+        _ = timestamp
+        path = File.path(path)
+        codepoints = Array(unicodes).map(&:to_i) + text.to_s.codepoints
+        gids = native_glyph_ids(path, codepoints, File.basename(path))
+        native_subset(path, gids, profile.to_s)
+      end
+
+      def read(path, mode: :metadata, lazy: true)
+        native_read(File.path(path), mode.to_s == "metadata", lazy)
+      end
+
+      def audit(path, validate: false)
+        native_audit(File.path(path), validate ? true : false)
+      end
+
+      def scan(paths)
+        Array(paths).flat_map { |path| native_scan(File.path(path)) }
+      end
+
+      # Same entries as Reference.audit_dir. A file the engine leaves to Ruby
+      # (dfont, Type 1) is audited through the gate, so it is served and
+      # recorded as :ruby.
+      def audit_dir(dir, validate: false)
+        dir = File.path(dir)
+        native_audit_dir_rows(dir, validate ? true : false).filter_map do |row|
+          rel = Fontisan::Reference.relative_row_path(dir, row["path"])
+          next if rel.split("/").any? { |part| part.start_with?(".") }
+
+          dir_entry(dir, row, rel, validate)
+        end
+      end
+
+      def dir_entry(dir, row, rel, validate)
+        case row["status"]
+        when "ok" then { "faces" => row["reports"], "path" => rel }
+        # The gate records the path it is given and Engine.audit_dir looks it up
+        # as File.join(dir, rel); the row's own path has a native separator on
+        # Windows, so it would never match.
+        when "unsupported" then audit_with_ruby(File.join(dir, rel), rel, validate)
+        else
+          error = row["error"]
+          { "error" => { "class" => error["class"], "message" => error["message"] }, "path" => rel }
+        end
+      end
+
+      def audit_with_ruby(file, rel, validate)
+        { "faces" => Fontisan::Reference.audit(file, validate: validate), "path" => rel }
+      rescue StandardError => e
+        { "error" => { "class" => e.class.name, "message" => e.message }, "path" => rel }
+      end
+    end
+  end
+end