fontisan 0.2.16 → 0.2.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 356bd0157b272462910d8822c6b77a6c768e12a45f4c56b2646d6bc683413239
-  data.tar.gz: 981dca0c122d3d3e2dab683c6a7962bc2bcc1be35fb5c0818857d6c55ff7bbbf
+  metadata.gz: 42bca448396aff910f6d3c92ac31bfa68afdbb85b6f9217d996d73cdbb62af5c
+  data.tar.gz: 8e3a5ad55f4c4ba9ac4430caa9447b07ef317840559b84b936cc57791470ee3b
 SHA512:
-  metadata.gz: '0852e6bc36559c125cab91cf4fe4d65256628df2e8c873bc52b4f291b2adc944126ed2a0e26d6daafbe7d568934a9788677cb47c8b70982097320addbc93365a'
-  data.tar.gz: dc9d8fdacf95fc0761bb62cfec0f56e7a7da1a78986915db76243461cf2434d3f8142a0547e153d6746e242aa4a3a5dc33b5b505e8ac073e467e9b9c269d97bf
+  metadata.gz: de88ca7106b4934b37c0060f76f41b7972c0092a798c860cbc37795357ffdbce11089ae556f461c490c1fdd43ab48bc97ba3f1d90687abfb95fbea14d42259a7
+  data.tar.gz: 2aa4ccdca9901b1ce95eb442238530d86f24a52eae0e3eebfbd23470f3c614858b905adac85fa198fd6d3e8b66f3b6b762015575adff30bafbccd0c5c99115c7

data/Gemfile

@@ -5,12 +5,12 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in fontisan.gemspec
 gemspec
 
-gem "canon", "~> 0.1.3"
-gem "get_process_mem", "~> 0.2"
+gem "benchmark"
 # bigdecimal is required by get_process_mem for Ruby 3.4+ compatibility
 gem "bigdecimal"
+gem "canon", "~> 0.1.3"
+gem "get_process_mem", "~> 0.2"
 gem "openssl", "~> 3.0"
-# sys-proctable is required by get_process_mem on Windows
 gem "rake"
 gem "rspec"
 gem "rubocop"
@@ -18,4 +18,7 @@ gem "rubocop-performance"
 gem "rubocop-rake"
 gem "rubocop-rspec"
 gem "rubyzip"
+# sys-proctable is required by get_process_mem on Windows
 gem "sys-proctable", platforms: %i[mswin mingw mswin64]
+# win32ole was a default gem until Ruby 4.0 — pin it for Windows runners
+gem "win32ole", platforms: %i[mswin mingw mswin64]

data/docs/api/font-loader.md

@@ -40,9 +40,11 @@ font = Fontisan::FontLoader.load(File.read('font.ttf', mode: 'rb'))
 
 **Raises:** Fontisan::FormatError if format is unsupported
 
-### detect_format(source)
+### detect_format(path)
 
-Detect font format without loading.
+Detect a font's on-disk format from its content (magic bytes). The file
+extension is ignored — a `.ttc` that actually contains a single OpenType-CFF
+font is reported as `:otf`.
 
 ```ruby
 format = Fontisan::FontLoader.detect_format('font.ttf')
@@ -52,24 +54,28 @@ format = Fontisan::FontLoader.detect_format('font.otf')
 # => :otf
 
 format = Fontisan::FontLoader.detect_format('font.pfb')
-# => :type1
+# => :pfb
+
+format = Fontisan::FontLoader.detect_format('font.pfa')
+# => :pfa
 ```
 
-**Returns:** Symbol or nil
+**Returns:** Symbol (`:ttf`, `:otf`, `:ttc`, `:otc`, `:woff`, `:woff2`,
+`:dfont`, `:pfa`, `:pfb`) or `nil` if the format is not recognised.
 
 ## Supported Formats
 
-| Format | Detection | Notes |
-|--------|-----------|-------|
-| TTF | Magic number | TrueType |
-| OTF | Magic number | OpenType/CFF |
-| TTC | Magic number | TrueType Collection |
-| OTC | Magic number | OpenType Collection |
-| WOFF | Magic number | Web Open Font Format |
-| WOFF2 | Magic number | Web Open Font Format 2 |
-| PFB | Marker byte | Adobe Type 1 Binary |
-| PFA | Text | Adobe Type 1 ASCII |
-| dfont | Magic number | Apple Data Fork |
+| Symbol  | Detection   | Notes                          |
+|---------|-------------|--------------------------------|
+| `:ttf`   | Magic bytes | TrueType                       |
+| `:otf`   | Magic bytes | OpenType / CFF                 |
+| `:ttc`   | Magic bytes | TrueType Collection            |
+| `:otc`   | Magic bytes | OpenType Collection            |
+| `:woff`  | Magic bytes | Web Open Font Format           |
+| `:woff2` | Magic bytes | Web Open Font Format 2         |
+| `:pfb`   | Marker byte | Adobe Type 1 Binary            |
+| `:pfa`   | Text header | Adobe Type 1 ASCII             |
+| `:dfont` | Magic bytes | Apple Data-Fork resource fork  |
 
 ## Examples
 

data/fontisan.gemspec

@@ -41,6 +41,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "base64"
   spec.add_dependency "bindata", "~> 2.5"
   spec.add_dependency "brotli", "~> 0.5"
+  spec.add_dependency "logger"
   spec.add_dependency "lutaml-model", "~> 0.8"
   spec.add_dependency "nokogiri", "~> 1.16"
   spec.add_dependency "thor", "~> 1.3"

data/lib/fontisan/constants.rb

@@ -9,7 +9,7 @@ module Fontisan
   module Constants
     # TrueType Collection file signature tag.
     # All valid TTC files must begin with this 4-byte tag.
-    TTC_TAG = "ttcf"
+    TTC_TAG = "ttcf".b.freeze
 
     # TrueType Collection Version 1.0 identifier.
     # Represents the original TTC format version.
@@ -25,11 +25,23 @@ module Fontisan
     # SFNT version for OpenType fonts with CFF outlines ('OTTO')
     SFNT_VERSION_OTTO = 0x4F54544F
 
-    # Apple 'true' TrueType signature (alternate to 0x00010000)
-    SFNT_VERSION_TRUE = 0x74727965 # 'true' in ASCII
-
-    # dfont resource fork signatures
-    DFONT_RESOURCE_HEADER = "\x00\x00\x01\x00"
+    # Apple 'true' TrueType signature (alternate to 0x00010000).
+    # Bytes: 0x74 ('t') 0x72 ('r') 0x75 ('u') 0x65 ('e').
+    SFNT_VERSION_TRUE = 0x74727565
+
+    # Four-byte file signatures used for content-based format detection.
+    # Pre-packed once here so format detection doesn't repack on every call.
+    SFNT_TRUETYPE_MAGIC = "\x00\x01\x00\x00".b.freeze # packed SFNT_VERSION_TRUETYPE
+    SFNT_TRUE_MAGIC     = "true".b.freeze             # Apple legacy TrueType
+    SFNT_OTTO_MAGIC     = "OTTO".b.freeze             # OpenType / CFF
+    WOFF_MAGIC          = "wOFF".b.freeze
+    WOFF2_MAGIC         = "wOF2".b.freeze
+
+    # dfont resource fork signatures.
+    # Note: bytes differ from SFNT_TRUETYPE_MAGIC despite the visual similarity —
+    # dfont is "\x00\x00\x01\x00" (resource-data offset 256, big-endian),
+    # SFNT_TRUETYPE_MAGIC is "\x00\x01\x00\x00" (sfnt version 0x00010000).
+    DFONT_RESOURCE_HEADER = "\x00\x00\x01\x00".b.freeze
     SFNT_RESOURCE_TYPE = "sfnt"
     FOND_RESOURCE_TYPE = "FOND"
 
@@ -173,5 +185,16 @@ module Fontisan
     def self.intern_string(str)
       STRING_POOL[str] || str.freeze
     end
+
+    # Classify a 4-byte SFNT-style signature read from a font file's magic.
+    #
+    # @param signature [String, nil]
+    # @return [Symbol, nil] :ttf, :otf, or nil for unrecognised signatures
+    def self.sfnt_format_for(signature)
+      case signature
+      when SFNT_TRUETYPE_MAGIC, SFNT_TRUE_MAGIC then :ttf
+      when SFNT_OTTO_MAGIC then :otf
+      end
+    end
   end
 end

data/lib/fontisan/font_loader.rb

@@ -1,22 +1,31 @@
 # frozen_string_literal: true
 
+require "stringio"
 require_relative "constants"
 require_relative "loading_modes"
 require_relative "true_type_font"
 require_relative "open_type_font"
 require_relative "true_type_collection"
 require_relative "open_type_collection"
+require_relative "dfont_collection"
 require_relative "woff_font"
 require_relative "woff2_font"
 require_relative "type1_font"
+require_relative "parsers/dfont_parser"
 require_relative "error"
 
 module Fontisan
-  # FontLoader provides unified font loading with automatic format detection.
+  # FontLoader provides unified font loading with content-based format detection.
   #
   # This class is the primary entry point for loading fonts in Fontisan.
-  # It automatically detects the font format and returns the appropriate
-  # domain object (TrueTypeFont, OpenTypeFont, Type1Font, TrueTypeCollection, or OpenTypeCollection).
+  # It inspects each file's magic bytes to determine the on-disk format and
+  # returns the appropriate domain object (TrueTypeFont, OpenTypeFont,
+  # Type1Font, TrueTypeCollection, or OpenTypeCollection).
+  #
+  # Detection is purely content-based — the file extension is ignored. This
+  # matters because vendors occasionally ship files with a misleading
+  # extension (e.g. Apple ships a single OpenType-CFF font as `.ttc` in
+  # macOS's private FontServices framework).
   #
   # @example Load any font type
   #   font = FontLoader.load("font.ttf")  # => TrueTypeFont
@@ -34,7 +43,28 @@ 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
-    # Load a font from file with automatic format detection
+    # 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
+    # any SFNT-style or dfont magic.
+    PFA_PROBE_LENGTH = 100
+    private_constant :PFA_PROBE_LENGTH
+
+    # Map of collection format symbols to the class that loads them. Single
+    # source of truth for "what counts as a collection"; both {.collection?}
+    # and {.load_collection} dispatch off this table.
+    COLLECTION_CLASSES = {
+      ttc: TrueTypeCollection,
+      otc: OpenTypeCollection,
+      dfont: DfontCollection,
+    }.freeze
+    private_constant :COLLECTION_CLASSES
+
+    # Load a font from file with content-based format detection.
+    #
+    # The file's bytes determine its format; the extension is ignored. See
+    # {.detect_format} for the full list of recognised formats and how they
+    # are detected.
     #
     # @param path [String] Path to the font file
     # @param font_index [Integer] Index of font in collection (0-based, default: 0)
@@ -45,125 +75,87 @@ module Fontisan
     # @raise [UnsupportedFormatError] for unsupported formats
     # @raise [InvalidFontError] for corrupted or unknown formats
     def self.load(path, font_index: 0, mode: nil, lazy: nil)
-      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
-
-      # Resolve mode and lazy parameters with environment variables
       resolved_mode = mode || env_mode || LoadingModes::FULL
       resolved_lazy = if lazy.nil?
                         env_lazy.nil? ? false : env_lazy
                       else
                         lazy
                       end
-
-      # Validate mode
       LoadingModes.validate_mode!(resolved_mode)
 
-      # Check for Type 1 format first (PFB/PFA have different signatures)
-      if type1_font?(path)
-        return Type1Font.from_file(path, mode: resolved_mode)
-      end
-
-      File.open(path, "rb") do |io|
-        signature = io.read(4)
-        io.rewind
-
-        case signature
-        when Constants::TTC_TAG
-          load_from_collection(io, path, font_index, mode: resolved_mode,
-                                                     lazy: resolved_lazy)
-        when pack_uint32(Constants::SFNT_VERSION_TRUETYPE), "true"
-          TrueTypeFont.from_file(path, mode: resolved_mode, lazy: resolved_lazy)
-        when "OTTO"
-          OpenTypeFont.from_file(path, mode: resolved_mode, lazy: resolved_lazy)
-        when "wOFF"
-          WoffFont.from_file(path, mode: resolved_mode, lazy: resolved_lazy)
-        when "wOF2"
-          Woff2Font.from_file(path, mode: resolved_mode, lazy: resolved_lazy)
-        when Constants::DFONT_RESOURCE_HEADER
-          extract_and_load_dfont(io, path, font_index, resolved_mode,
-                                 resolved_lazy)
-        else
-          raise InvalidFontError,
-                "Unknown font format. Expected TTF, OTF, TTC, OTC, WOFF, WOFF2, PFB, or PFA file."
-        end
+      format = detect(path)
+      case format
+      when :ttf   then TrueTypeFont.from_file(path, mode: resolved_mode, lazy: resolved_lazy)
+      when :otf   then OpenTypeFont.from_file(path, mode: resolved_mode, lazy: resolved_lazy)
+      when :woff  then WoffFont.from_file(path, mode: resolved_mode, lazy: resolved_lazy)
+      when :woff2 then Woff2Font.from_file(path, mode: resolved_mode, lazy: resolved_lazy)
+      when :ttc, :otc then load_from_collection(path, format, font_index, mode: resolved_mode)
+      when :dfont then load_dfont(path, font_index: font_index, mode: resolved_mode)
+      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."
       end
     end
 
-    # Check if a file is a collection (TTC or OTC)
+    # Check if a file is a collection (TTC, OTC, or dfont).
+    #
+    # Returns `false` for a ttcf-headed file whose inner fonts can't be
+    # classified (truncated header, offsets past EOF, unrecognised inner
+    # SFNT versions). Such a file is structurally invalid as a collection
+    # and would fail to load, so reporting it as "not a collection" matches
+    # what callers can actually do with it.
     #
     # @param path [String] Path to the font file
-    # @return [Boolean] true if file is a TTC/OTC collection
+    # @return [Boolean] true if file is a loadable collection
     # @raise [Errno::ENOENT] if file does not exist
     #
     # @example Check if file is collection
     #   FontLoader.collection?("fonts.ttc") # => true
     #   FontLoader.collection?("font.ttf")  # => false
-    def self.collection?(path)
-      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
-
-      File.open(path, "rb") do |io|
-        signature = io.read(4)
-        io.rewind
-
-        # Check for TTC/OTC signature
-        return true if signature == Constants::TTC_TAG
-
-        # Check for dfont - dfont is a collection format even if it contains only one font
-        if signature == Constants::DFONT_RESOURCE_HEADER
-          require_relative "parsers/dfont_parser"
-          return Parsers::DfontParser.dfont?(io)
-        end
-
-        false
-      end
-    end
+    def self.collection?(path) = COLLECTION_CLASSES.key?(detect(path))
 
-    # Load a collection object without extracting fonts
-    #
-    # Returns the collection object (TrueTypeCollection, OpenTypeCollection, or DfontCollection)
-    # without extracting individual fonts. Useful for inspecting collection
-    # metadata and structure.
+    # Identify a font file by inspecting its magic bytes (content-based detection).
     #
-    # = Collection Format Understanding
+    # Returns the actual on-disk format regardless of the file extension. This
+    # is the authoritative way to determine how a file should be parsed,
+    # because vendors occasionally ship files with a misleading extension
+    # (for example, Apple ships a single OpenType-CFF font as `.ttc` in
+    # macOS's private FontServices framework).
     #
-    # Both TTC (TrueType Collection) and OTC (OpenType Collection) files use
-    # the same "ttcf" signature. The distinction between TTC and OTC is NOT
-    # in the collection format itself, but in the fonts contained within:
+    # Collections are distinguished by scanning the inner fonts: if any inner
+    # font is OpenType (CFF), the file is reported as `:otc`; otherwise (all
+    # inner fonts are TrueType) it is reported as `:ttc`. A ttcf-headed file
+    # whose inner fonts can't be classified (truncated header, offsets past
+    # EOF, unrecognised inner SFNT versions) returns `nil`. dfont detection
+    # uses the canonical resource-data-offset (256) magic only; non-canonical
+    # but structurally valid dfonts are accepted by {.load_collection} as a
+    # fallback but not reported here.
     #
-    # - TTC typically contains TrueType fonts (glyf outlines)
-    # - OTC typically contains OpenType fonts (CFF/CFF2 outlines)
-    # - Mixed collections are possible (both TTF and OTF in same collection)
-    #
-    # dfont (Data Fork Font) is an Apple-specific format that contains Mac
-    # font suitcase resources. It can contain multiple SFNT fonts (TrueType
-    # or OpenType).
-    #
-    # Each collection can contain multiple SFNT-format font files, with table
-    # deduplication to save space. Individual fonts within a collection are
-    # stored at different offsets within the file, each with their own table
-    # directory and data tables.
-    #
-    # = Detection Strategy
+    # @param path [String] Path to the font file
+    # @return [Symbol, nil] One of `:ttf`, `:otf`, `:ttc`, `:otc`, `:woff`,
+    #   `:woff2`, `:dfont`, `:pfa`, `:pfb`, or `nil` when the format is not
+    #   recognised.
+    # @raise [Errno::ENOENT] if the file does not exist
     #
-    # This method scans ALL fonts in the collection to determine the collection
-    # type accurately:
+    # @example Detect a real collection
+    #   FontLoader.detect_format("fonts.ttc")          # => :ttc
     #
-    # 1. Reads all font offsets from the collection header
-    # 2. Examines the sfnt_version of each font in the collection
-    # 3. Counts TrueType fonts (0x00010000 or 0x74727565 "true") vs OpenType fonts (0x4F54544F "OTTO")
-    # 4. If ANY font is OpenType (CFF), returns OpenTypeCollection
-    # 5. Only returns TrueTypeCollection if ALL fonts are TrueType
+    # @example Detect a single OTF mislabeled as .ttc
+    #   FontLoader.detect_format("SauberScript.ttc")   # => :otf
+    def self.detect_format(path) = detect(path)
+
+    # Load a collection object without extracting fonts
     #
-    # For dfont files, returns DfontCollection.
+    # Returns the collection object (TrueTypeCollection, OpenTypeCollection,
+    # or DfontCollection) without extracting individual fonts. Useful for
+    # inspecting collection metadata and structure.
     #
-    # This approach correctly handles:
-    # - Homogeneous collections (all TTF or all OTF)
-    # - Mixed collections (both TTF and OTF fonts) - uses OpenTypeCollection
-    # - Large collections with many fonts (like NotoSerifCJK.ttc with 35 fonts)
-    # - dfont suitcases (Apple-specific)
+    # The TTC vs. OTC distinction is resolved by {.detect_format}, which
+    # scans the inner fonts; see that method for details.
     #
     # @param path [String] Path to the collection file
-    # @return [TrueTypeCollection, OpenTypeCollection, DfontCollection] The collection object
+    # @return [TrueTypeCollection, OpenTypeCollection, DfontCollection]
     # @raise [Errno::ENOENT] if file does not exist
     # @raise [InvalidFontError] if file is not a collection or type cannot be determined
     #
@@ -171,69 +163,88 @@ module Fontisan
     #   collection = FontLoader.load_collection("fonts.ttc")
     #   puts "Collection has #{collection.num_fonts} fonts"
     def self.load_collection(path)
-      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
+      format = detect(path)
+      return COLLECTION_CLASSES.fetch(format).from_file(path) if COLLECTION_CLASSES.key?(format)
 
+      # Lenient fallback: a dfont whose resource-data offset isn't the
+      # canonical 256 fails the strict magic test in {.detect} but may still
+      # be structurally valid; try the structural check before giving up.
       File.open(path, "rb") do |io|
-        signature = io.read(4)
-        io.rewind
-
-        # Check for dfont
-        if signature == Constants::DFONT_RESOURCE_HEADER || dfont_signature?(io)
-          require_relative "dfont_collection"
-          return DfontCollection.from_file(path)
-        end
-
-        # Check for TTC/OTC
-        unless signature == Constants::TTC_TAG
-          raise InvalidFontError,
-                "File is not a collection (TTC/OTC/dfont). Use FontLoader.load instead."
-        end
-
-        # Read version and num_fonts
-        io.seek(8) # Skip tag (4) + version (4)
-        num_fonts = io.read(4).unpack1("N")
-
-        # Read all font offsets
-        font_offsets = Array.new(num_fonts) { io.read(4).unpack1("N") }
+        return DfontCollection.from_file(path) if Parsers::DfontParser.dfont?(io)
+      end
+      raise InvalidFontError,
+            "File is not a collection (TTC/OTC/dfont). Use FontLoader.load instead."
+    end
 
-        # Scan all fonts to determine collection type (not just first)
-        truetype_count = 0
-        opentype_count = 0
+    # Content-based detection. Reads 4 bytes first (covers every SFNT-style
+    # and canonical dfont magic), then tops up to {PFA_PROBE_LENGTH} for
+    # Type 1 only on an SFNT miss.
+    def self.detect(path)
+      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
 
-        font_offsets.each do |offset|
-          io.rewind
-          io.seek(offset)
-          sfnt_version = io.read(4).unpack1("N")
+      File.open(path, "rb") do |io|
+        head4 = io.read(4)
+        return nil if head4.nil? || head4.empty?
+
+        sfnt = case head4
+               when Constants::TTC_TAG then scan_collection(io)
+               when Constants::SFNT_OTTO_MAGIC then :otf
+               when Constants::SFNT_TRUETYPE_MAGIC, Constants::SFNT_TRUE_MAGIC then :ttf
+               when Constants::WOFF_MAGIC then :woff
+               when Constants::WOFF2_MAGIC then :woff2
+               when Constants::DFONT_RESOURCE_HEADER
+                 io.rewind
+                 Parsers::DfontParser.dfont?(io) ? :dfont : nil
+               end
+        return sfnt if sfnt
+
+        rest = head4.bytesize < PFA_PROBE_LENGTH ? io.read(PFA_PROBE_LENGTH - head4.bytesize) : nil
+        type1_format_from_header(rest ? head4 + rest : head4)
+      end
+    end
 
-          case sfnt_version
-          when Constants::SFNT_VERSION_TRUETYPE, 0x74727565 # 0x74727565 = 'true'
-            truetype_count += 1
-          when Constants::SFNT_VERSION_OTTO
-            opentype_count += 1
-          else
-            raise InvalidFontError,
-                  "Unknown font type in collection at offset #{offset} (sfnt version: 0x#{sfnt_version.to_s(16)})"
-          end
+    # Identify the Type 1 sub-format (`:pfa` or `:pfb`) from a probe of the
+    # file's leading bytes. Returns nil if the bytes don't match Type 1.
+    def self.type1_format_from_header(header)
+      if header.bytesize >= 2
+        marker = (header.getbyte(0) << 8) | header.getbyte(1)
+        if [Constants::PFB_ASCII_CHUNK, Constants::PFB_BINARY_CHUNK].include?(marker)
+          return :pfb
         end
+      end
+
+      # PFA is plain text — the Adobe Type 1 header must appear at the very
+      # start (allowing only leading ASCII whitespace), not anywhere in the
+      # probe. Using start_with? avoids matching a non-Type-1 PostScript file
+      # that happens to mention the signature in a comment.
+      stripped = header.lstrip
+      if stripped.start_with?(Constants::PFA_SIGNATURE_ADOBE_1_0, Constants::PFA_SIGNATURE_ADOBE_3_0)
+        return :pfa
+      end
 
-        io.rewind
+      nil
+    end
 
-        # Determine collection type based on what fonts are inside
-        # If ANY font is OpenType, use OpenTypeCollection (more general format)
-        # Only use TrueTypeCollection if ALL fonts are TrueType
-        if opentype_count.positive?
-          OpenTypeCollection.from_file(path)
-        else
-          # All fonts are TrueType
-          TrueTypeCollection.from_file(path)
+    # Walk a ttcf-headed file via BaseCollection. Returns `:ttc`, `:otc`, or
+    # nil for any truncation, unreadable offset, or unrecognised inner magic.
+    def self.scan_collection(io)
+      io.rewind
+      header = BaseCollection.read(io)
+      has_otf = false
+      header.font_offsets.each do |offset|
+        io.seek(offset)
+        case Constants.sfnt_format_for(io.read(4))
+        when :otf then has_otf = true
+        when :ttf then next
+        else return nil
         end
       end
+      has_otf ? :otc : :ttc
+    rescue BinData::ValidityError, IOError
+      nil
     end
 
-    # Get mode from environment variable
-    #
-    # @return [Symbol, nil] Mode from FONTISAN_MODE or nil
-    # @api private
+    # Mode override from FONTISAN_MODE env var, or nil.
     def self.env_mode
       env_value = ENV["FONTISAN_MODE"]
       return nil unless env_value
@@ -242,10 +253,7 @@ module Fontisan
       LoadingModes.valid_mode?(mode) ? mode : nil
     end
 
-    # Get lazy setting from environment variable
-    #
-    # @return [Boolean, nil] Lazy setting from FONTISAN_LAZY or nil if not set
-    # @api private
+    # Lazy override from FONTISAN_LAZY env var, or nil.
     def self.env_lazy
       env_value = ENV["FONTISAN_LAZY"]
       return nil unless env_value
@@ -253,182 +261,40 @@ module Fontisan
       env_value.downcase == "true"
     end
 
-    # Load from a collection file (TTC or OTC)
-    #
-    # This is the internal method that handles loading individual fonts from
-    # collection files. It reads the collection header to determine the type
-    # (TTC vs OTC) and extracts the requested font.
-    #
-    # = Collection Header Structure
-    #
-    # TTC/OTC files start with:
-    # - Bytes 0-3: "ttcf" tag (4 bytes)
-    # - Bytes 4-7: version (2 bytes major + 2 bytes minor)
-    # - Bytes 8-11: num_fonts (4 bytes, big-endian uint32)
-    # - Bytes 12+: font offset array (4 bytes per font, big-endian uint32)
-    #
-    # CRITICAL: The method seeks to position 8 (after tag and version) to read
-    # num_fonts, NOT position 12 which is where the offset array starts. This
-    # was a bug that caused "Unknown font type" errors when the first offset
-    # was misread as num_fonts.
-    #
-    # @param io [IO] Open file handle
-    # @param path [String] Path to the collection file
-    # @param font_index [Integer] Index of font to extract
-    # @param mode [Symbol] Loading mode (:metadata or :full)
-    # @param lazy [Boolean] If true, load tables on demand
-    # @return [TrueTypeFont, OpenTypeFont] The loaded font object
-    # @raise [InvalidFontError] if collection type cannot be determined
-    def self.load_from_collection(io, path, font_index,
-mode: LoadingModes::FULL, lazy: true)
-      # Read collection header to get font offsets
-      io.seek(8) # Skip tag (4) + version (4)
-      num_fonts = io.read(4).unpack1("N")
-
-      if font_index >= num_fonts
+    # Load a single font from a TTC/OTC collection. `format` is the detected
+    # symbol routed from `.load`'s case statement, so no second magic read.
+    def self.load_from_collection(path, format, font_index, mode:)
+      collection = COLLECTION_CLASSES.fetch(format).from_file(path)
+      if font_index >= collection.num_fonts
         raise InvalidFontError,
-              "Font index #{font_index} out of range (collection has #{num_fonts} fonts)"
-      end
-
-      # Read all font offsets
-      font_offsets = Array.new(num_fonts) { io.read(4).unpack1("N") }
-
-      # Scan all fonts to determine collection type (not just first)
-      truetype_count = 0
-      opentype_count = 0
-
-      font_offsets.each do |offset|
-        io.rewind
-        io.seek(offset)
-        sfnt_version = io.read(4).unpack1("N")
-
-        case sfnt_version
-        when Constants::SFNT_VERSION_TRUETYPE, 0x74727565 # 0x74727565 = 'true'
-          truetype_count += 1
-        when Constants::SFNT_VERSION_OTTO
-          opentype_count += 1
-        else
-          raise InvalidFontError,
-                "Unknown font type in collection at offset #{offset} (sfnt version: 0x#{sfnt_version.to_s(16)})"
-        end
+              "Font index #{font_index} out of range (collection has #{collection.num_fonts} fonts)"
       end
 
-      io.rewind
-
-      # If ANY font is OpenType, use OpenTypeCollection (more general format)
-      # Only use TrueTypeCollection if ALL fonts are TrueType
-      if opentype_count.positive?
-        # OpenType Collection
-        otc = OpenTypeCollection.from_file(path)
-        File.open(path, "rb") { |f| otc.font(font_index, f, mode: mode) }
-      else
-        # TrueType Collection (all fonts are TrueType)
-        ttc = TrueTypeCollection.from_file(path)
-        File.open(path, "rb") { |f| ttc.font(font_index, f, mode: mode) }
-      end
+      File.open(path, "rb") { |io| collection.font(font_index, io, mode: mode) }
     end
 
-    # Extract and load font from dfont resource fork
-    #
-    # @param io [IO] Open file handle
-    # @param path [String] Path to dfont file
-    # @param font_index [Integer] Font index in suitcase
-    # @param mode [Symbol] Loading mode
-    # @param lazy [Boolean] Lazy loading flag
-    # @return [TrueTypeFont, OpenTypeFont] Loaded font
-    # @api private
-    def self.extract_and_load_dfont(io, _path, font_index, mode, lazy)
-      require_relative "parsers/dfont_parser"
-
-      # Extract SFNT data from resource fork
-      sfnt_data = Parsers::DfontParser.extract_sfnt(io, index: font_index)
-
-      # Create StringIO with SFNT data
-      sfnt_io = StringIO.new(sfnt_data)
-
-      # Detect SFNT signature
-      signature = sfnt_io.read(4)
-      sfnt_io.rewind
-
-      # Read and setup font based on signature
-      case signature
-      when pack_uint32(Constants::SFNT_VERSION_TRUETYPE), "true"
-        font = TrueTypeFont.read(sfnt_io)
-        font.initialize_storage
-        font.loading_mode = mode
-        font.lazy_load_enabled = lazy
-        font.read_table_data(sfnt_io) unless lazy
-        font
-      when "OTTO"
-        font = OpenTypeFont.read(sfnt_io)
-        font.initialize_storage
-        font.loading_mode = mode
-        font.lazy_load_enabled = lazy
-        font.read_table_data(sfnt_io) unless lazy
-        font
-      else
-        raise InvalidFontError,
-              "Invalid SFNT data in dfont resource (signature: #{signature.inspect})"
-      end
-    end
-
-    # Pack uint32 value to big-endian bytes
-    #
-    # @param value [Integer] The uint32 value
-    # @return [String] 4-byte binary string
-    # @api private
-    def self.pack_uint32(value)
-      [value].pack("N")
-    end
-
-    private_class_method :load_from_collection, :pack_uint32, :env_mode,
-                         :env_lazy, :extract_and_load_dfont
-
-    # Check if file has dfont signature
-    #
-    # @param io [IO] Open file handle
-    # @return [Boolean] true if dfont
-    # @api private
-    def self.dfont_signature?(io)
-      require_relative "parsers/dfont_parser"
-      Parsers::DfontParser.dfont?(io)
-    end
-
-    private_class_method :dfont_signature?
-
-    # Check if file is a Type 1 font (PFB or PFA)
-    #
-    # Type 1 fonts come in two formats:
-    # - PFB (Printer Font Binary): Binary format with chunk markers
-    # - PFA (Printer Font ASCII): ASCII text format with hex encoding
-    #
-    # @param path [String] Path to the font file
-    # @return [Boolean] true if Type 1 font
-    # @api private
-    def self.type1_font?(path)
-      # Check file extension first (quick check)
-      ext = File.extname(path).downcase
-      return true if [".pfb", ".pfa", ".ps"].include?(ext)
-
-      # Check PFB signature (first byte should be 0x80 or 0x81)
+    # Extract an SFNT from a dfont resource fork into memory and load it via
+    # `SfntFont.from_collection` so the loading-mode handling matches the
+    # TTC/OTC path. Lazy loading is a no-op for in-memory StringIO so the
+    # public `lazy:` flag is not threaded through this path.
+    def self.load_dfont(path, font_index:, mode:)
       File.open(path, "rb") do |io|
-        first_byte = io.getbyte
-        return true if [Constants::PFB_ASCII_CHUNK, Constants::PFB_BINARY_CHUNK].include?(first_byte)
+        sfnt_io = StringIO.new(Parsers::DfontParser.extract_sfnt(io, index: font_index))
+        klass = case Constants.sfnt_format_for(sfnt_io.read(4))
+                when :ttf then TrueTypeFont
+                when :otf then OpenTypeFont
+                else raise InvalidFontError, "Invalid SFNT in dfont resource"
+                end
+        klass.from_collection(sfnt_io, 0, mode: mode)
       end
-
-      # Check PFA signature (text file with Adobe header)
-      File.open(path, "rb") do |io|
-        # Read first 100 bytes to check for PFA signature
-        header = io.read(100)
-        return true if header.include?(Constants::PFA_SIGNATURE_ADOBE_1_0) ||
-          header.include?(Constants::PFA_SIGNATURE_ADOBE_3_0)
-      end
-
-      false
-    rescue IOError, Errno::ENOENT
-      false
     end
 
-    private_class_method :type1_font?
+    private_class_method :detect,
+                         :type1_format_from_header,
+                         :scan_collection,
+                         :env_mode,
+                         :env_lazy,
+                         :load_from_collection,
+                         :load_dfont
   end
 end

data/lib/fontisan/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fontisan
-  VERSION = "0.2.16"
+  VERSION = "0.2.17"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fontisan
 version: !ruby/object:Gem::Version
-  version: 0.2.16
+  version: 0.2.17
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-02 00:00:00.000000000 Z
+date: 2026-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: lutaml-model
   requirement: !ruby/object:Gem::Requirement