fontisan 0.2.5 → 0.2.7

data/lib/fontisan/font_loader.rb

@@ -63,7 +63,7 @@ module Fontisan
         when Constants::TTC_TAG
           load_from_collection(io, path, font_index, mode: resolved_mode,
                                                      lazy: resolved_lazy)
-        when pack_uint32(Constants::SFNT_VERSION_TRUETYPE)
+        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)
@@ -71,6 +71,8 @@ module Fontisan
           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, or WOFF2 file."
@@ -92,13 +94,24 @@ module Fontisan
 
       File.open(path, "rb") do |io|
         signature = io.read(4)
-        signature == Constants::TTC_TAG
+        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
 
     # Load a collection object without extracting fonts
     #
-    # Returns the collection object (TrueTypeCollection or OpenTypeCollection)
+    # Returns the collection object (TrueTypeCollection, OpenTypeCollection, or DfontCollection)
     # without extracting individual fonts. Useful for inspecting collection
     # metadata and structure.
     #
@@ -112,6 +125,10 @@ module Fontisan
     # - 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
@@ -128,13 +145,16 @@ module Fontisan
     # 4. If ANY font is OpenType (CFF), returns OpenTypeCollection
     # 5. Only returns TrueTypeCollection if ALL fonts are TrueType
     #
+    # For dfont files, returns DfontCollection.
+    #
     # 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)
     #
     # @param path [String] Path to the collection file
-    # @return [TrueTypeCollection, OpenTypeCollection] The collection object
+    # @return [TrueTypeCollection, OpenTypeCollection, DfontCollection] The collection object
     # @raise [Errno::ENOENT] if file does not exist
     # @raise [InvalidFontError] if file is not a collection or type cannot be determined
     #
@@ -146,10 +166,18 @@ module Fontisan
 
       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). Use FontLoader.load instead."
+                "File is not a collection (TTC/OTC/dfont). Use FontLoader.load instead."
         end
 
         # Read version and num_fonts
@@ -291,6 +319,50 @@ mode: LoadingModes::FULL, lazy: true)
       end
     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
@@ -301,6 +373,18 @@ mode: LoadingModes::FULL, lazy: true)
     end
 
     private_class_method :load_from_collection, :pack_uint32, :env_mode,
-                         :env_lazy
+                         :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?
   end
 end

data/lib/fontisan/parsers/dfont_parser.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "bindata"
+require_relative "../error"
+
+module Fontisan
+  module Parsers
+    # Parser for Apple dfont (Data Fork Font) resource fork format.
+    #
+    # dfont files store resource fork data in the data fork, containing
+    # TrueType or OpenType SFNT data embedded in a resource fork structure.
+    #
+    # @example Extract SFNT from dfont
+    #   File.open("font.dfont", "rb") do |io|
+    #     sfnt_data = DfontParser.extract_sfnt(io)
+    #     # sfnt_data is raw SFNT binary
+    #   end
+    class DfontParser
+      # Resource fork header structure (16 bytes)
+      class ResourceHeader < BinData::Record
+        endian :big
+        uint32 :resource_data_offset    # Offset to resource data section
+        uint32 :resource_map_offset     # Offset to resource map
+        uint32 :resource_data_length    # Length of resource data
+        uint32 :resource_map_length     # Length of resource map
+      end
+
+      # Resource type entry in type list
+      class ResourceType < BinData::Record
+        endian :big
+        string :type_code, length: 4        # Resource type (e.g., 'sfnt')
+        uint16 :resource_count_minus_1      # Number of resources - 1
+        uint16 :reference_list_offset       # Offset to reference list
+      end
+
+      # Resource reference in reference list
+      class ResourceReference < BinData::Record
+        endian :big
+        uint16 :resource_id           # Resource ID
+        int16 :name_offset            # Offset to name in name list (-1 if none)
+        uint8 :attributes             # Resource attributes
+        bit24 :data_offset            # Offset to data (relative to resource data section)
+        uint32 :reserved              # Reserved (handle to resource in memory)
+      end
+
+      # Extract SFNT data from dfont file
+      #
+      # @param io [IO] Open file handle
+      # @param index [Integer] Font index for multi-font suitcases (default: 0)
+      # @return [String] Raw SFNT binary data
+      # @raise [InvalidFontError] if not valid dfont or index out of range
+      def self.extract_sfnt(io, index: 0)
+        header = parse_header(io)
+        sfnt_resources = find_sfnt_resources(io, header)
+
+        if sfnt_resources.empty?
+          raise InvalidFontError, "No sfnt resources found in dfont file"
+        end
+
+        if index >= sfnt_resources.length
+          raise InvalidFontError,
+                "Font index #{index} out of range (dfont has #{sfnt_resources.length} fonts)"
+        end
+
+        extract_resource_data(io, header, sfnt_resources[index])
+      end
+
+      # Count number of sfnt resources (fonts) in dfont
+      #
+      # @param io [IO] Open file handle
+      # @return [Integer] Number of fonts
+      def self.sfnt_count(io)
+        header = parse_header(io)
+        sfnt_resources = find_sfnt_resources(io, header)
+        sfnt_resources.length
+      end
+
+      # Check if file is valid dfont resource fork
+      #
+      # @param io [IO] Open file handle
+      # @return [Boolean]
+      def self.dfont?(io)
+        io.rewind
+        header_bytes = io.read(16)
+        io.rewind
+
+        return false if header_bytes.nil? || header_bytes.length < 16
+
+        # Basic sanity check on resource fork structure
+        data_offset = header_bytes[0..3].unpack1("N")
+        map_offset = header_bytes[4..7].unpack1("N")
+
+        data_offset.positive? && map_offset > data_offset
+      end
+
+      # Parse resource fork header
+      #
+      # @param io [IO] Open file handle
+      # @return [ResourceHeader] Parsed header
+      # @raise [InvalidFontError] if header invalid
+      # @api private
+      def self.parse_header(io)
+        io.rewind
+        ResourceHeader.read(io)
+      rescue BinData::ValidityError => e
+        raise InvalidFontError, "Invalid dfont resource header: #{e.message}"
+      end
+
+      # Find all sfnt resources in resource map
+      #
+      # @param io [IO] Open file handle
+      # @param header [ResourceHeader] Parsed header
+      # @return [Array<Hash>] Array of resource info hashes with :id and :offset
+      # @api private
+      def self.find_sfnt_resources(io, header)
+        # Seek to resource map
+        io.seek(header.resource_map_offset)
+
+        # Skip resource map header (22 bytes reserved + 4 bytes attributes + 2 bytes type list offset + 2 bytes name list offset)
+        # The actual layout is:
+        # - Bytes 0-15: Copy of resource header (16 bytes)
+        # - Bytes 16-19: Reserved for handle to next resource map (4 bytes)
+        # - Bytes 20-21: Reserved for file reference number (2 bytes)
+        # - Bytes 22-23: Resource file attributes (2 bytes)
+        # - Bytes 24-25: Offset to type list (2 bytes)
+        # - Bytes 26-27: Offset to name list (2 bytes)
+        io.seek(header.resource_map_offset + 24)
+
+        # Read type list offset (relative to start of resource map)
+        type_list_offset = io.read(2).unpack1("n")
+
+        # Seek to type list
+        io.seek(header.resource_map_offset + type_list_offset)
+
+        # Read number of types minus 1
+        type_count_minus_1 = io.read(2).unpack1("n")
+        type_count = type_count_minus_1 + 1
+
+        # Find 'sfnt' type in type list
+        sfnt_type = nil
+        type_count.times do
+          type_entry = ResourceType.read(io)
+
+          if type_entry.type_code == "sfnt"
+            sfnt_type = type_entry
+            break
+          end
+        end
+
+        return [] unless sfnt_type
+
+        # Read reference list for sfnt resources
+        reference_list_offset = header.resource_map_offset + type_list_offset + sfnt_type.reference_list_offset
+        io.seek(reference_list_offset)
+
+        resource_count = sfnt_type.resource_count_minus_1 + 1
+        resources = []
+
+        resource_count.times do
+          ref = ResourceReference.read(io)
+          resources << { id: ref.resource_id, offset: ref.data_offset }
+        end
+
+        resources
+      end
+
+      # Extract resource data at specific offset
+      #
+      # @param io [IO] Open file handle
+      # @param header [ResourceHeader] Parsed header
+      # @param resource_info [Hash] Resource info with :offset
+      # @return [String] Raw SFNT binary data
+      # @api private
+      def self.extract_resource_data(io, header, resource_info)
+        # Calculate absolute offset to resource data
+        # The offset in the reference is relative to the start of the resource data section
+        data_offset = header.resource_data_offset + resource_info[:offset]
+
+        io.seek(data_offset)
+
+        # Read data length (first 4 bytes of resource data)
+        data_length = io.read(4).unpack1("N")
+
+        # Read the actual data
+        io.read(data_length)
+      end
+
+      private_class_method :parse_header, :find_sfnt_resources,
+                           :extract_resource_data
+    end
+  end
+end

data/lib/fontisan/true_type_font.rb

@@ -69,12 +69,6 @@ module Fontisan
     # Whether lazy loading is enabled
     attr_accessor :lazy_load_enabled
 
-    # Page cache for lazy loading (maps page_start_offset => page_data)
-    attr_accessor :page_cache
-
-    # Page size for lazy loading alignment (typical filesystem page size)
-    PAGE_SIZE = 4096
-
     # Read TrueType Font from a file
     #
     # @param path [String] Path to the TTF file
@@ -101,8 +95,9 @@ module Fontisan
         font.lazy_load_enabled = lazy
 
         if lazy
-          # Keep file handle open for lazy loading
-          font.io_source = File.open(path, "rb")
+          # Reuse existing IO handle by duplicating it to prevent double file open
+          # The dup ensures the handle stays open after this block closes
+          font.io_source = io.dup
           font.setup_finalizer
         else
           # Read tables upfront
@@ -141,7 +136,6 @@ module Fontisan
       @loading_mode = LoadingModes::FULL
       @lazy_load_enabled = false
       @io_source = nil
-      @page_cache = {}
     end
 
     # Read table data for all tables
@@ -450,8 +444,8 @@ module Fontisan
 
     # Load a single table's data on demand
     #
-    # Uses page-aligned reads and caches pages to ensure lazy loading
-    # performance is not slower than eager loading.
+    # Uses direct seek-and-read for minimal overhead. This ensures lazy loading
+    # performance is comparable to eager loading when accessing all tables.
     #
     # @param tag [String] The table tag to load
     # @return [void]
@@ -461,42 +455,10 @@ module Fontisan
       entry = find_table_entry(tag)
       return nil unless entry
 
-      # Use page-aligned reading with caching
-      table_start = entry.offset
-      table_end = entry.offset + entry.table_length
-
-      # Calculate page boundaries
-      page_start = (table_start / PAGE_SIZE) * PAGE_SIZE
-      page_end = ((table_end + PAGE_SIZE - 1) / PAGE_SIZE) * PAGE_SIZE
-
-      # Read all required pages (or use cached pages)
-      table_data_parts = []
-      current_page = page_start
-
-      while current_page < page_end
-        page_data = @page_cache[current_page]
-
-        unless page_data
-          # Read page from disk and cache it
-          @io_source.seek(current_page)
-          page_data = @io_source.read(PAGE_SIZE) || ""
-          @page_cache[current_page] = page_data
-        end
-
-        # Calculate which part of this page we need
-        chunk_start = [table_start - current_page, 0].max
-        chunk_end = [table_end - current_page, PAGE_SIZE].min
-
-        if chunk_end > chunk_start
-          table_data_parts << page_data[chunk_start...chunk_end]
-        end
-
-        current_page += PAGE_SIZE
-      end
-
-      # Combine parts and store
+      # Direct seek and read - same as eager loading but on-demand
+      @io_source.seek(entry.offset)
       tag_key = tag.dup.force_encoding("UTF-8")
-      @table_data[tag_key] = table_data_parts.join
+      @table_data[tag_key] = @io_source.read(entry.table_length)
     end
 
     # Parse a table from raw data (Fontisan extension)

data/lib/fontisan/validation/collection_validator.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Fontisan
+  module Validation
+    # CollectionValidator validates font compatibility for collection formats
+    #
+    # Main responsibility: Enforce format-specific compatibility rules for
+    # TTC, OTC, and dfont collections according to OpenType spec and Apple standards.
+    #
+    # Rules:
+    # - TTC: TrueType fonts ONLY (per OpenType spec)
+    # - OTC: CFF fonts required, mixed TTF+OTF allowed (Fontisan extension)
+    # - dfont: Any SFNT fonts (TTF, OTF, or mixed)
+    # - All: Web fonts (WOFF/WOFF2) are NEVER allowed in collections
+    #
+    # @example Validate TTC compatibility
+    #   validator = CollectionValidator.new
+    #   validator.validate!([font1, font2], :ttc)
+    #
+    # @example Check compatibility without raising
+    #   validator = CollectionValidator.new
+    #   result = validator.compatible?([font1, font2], :otc)
+    class CollectionValidator
+      # Validate fonts are compatible with collection format
+      #
+      # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Fonts to validate
+      # @param format [Symbol] Collection format (:ttc, :otc, or :dfont)
+      # @return [Boolean] true if valid
+      # @raise [Error] if validation fails
+      def validate!(fonts, format)
+        validate_not_empty!(fonts)
+        validate_format!(format)
+
+        case format
+        when :ttc
+          validate_ttc!(fonts)
+        when :otc
+          validate_otc!(fonts)
+        when :dfont
+          validate_dfont!(fonts)
+        else
+          raise Error, "Unknown collection format: #{format}"
+        end
+
+        true
+      end
+
+      # Check if fonts are compatible with format (without raising)
+      #
+      # @param fonts [Array] Fonts to check
+      # @param format [Symbol] Collection format
+      # @return [Boolean] true if compatible
+      def compatible?(fonts, format)
+        validate!(fonts, format)
+        true
+      rescue Error
+        false
+      end
+
+      # Get compatibility issues for fonts and format
+      #
+      # @param fonts [Array] Fonts to check
+      # @param format [Symbol] Collection format
+      # @return [Array<String>] Array of issue descriptions (empty if compatible)
+      def compatibility_issues(fonts, format)
+        issues = []
+
+        return ["Font array cannot be empty"] if fonts.nil? || fonts.empty?
+        return ["Invalid format: #{format}"] unless %i[ttc otc dfont].include?(format)
+
+        case format
+        when :ttc
+          issues.concat(ttc_issues(fonts))
+        when :otc
+          issues.concat(otc_issues(fonts))
+        when :dfont
+          issues.concat(dfont_issues(fonts))
+        end
+
+        issues
+      end
+
+      private
+
+      # Validate fonts array is not empty
+      #
+      # @param fonts [Array] Fonts
+      # @raise [ArgumentError] if empty or nil
+      def validate_not_empty!(fonts)
+        if fonts.nil? || fonts.empty?
+          raise ArgumentError, "Font array cannot be empty"
+        end
+      end
+
+      # Validate format is supported
+      #
+      # @param format [Symbol] Format
+      # @raise [ArgumentError] if invalid
+      def validate_format!(format)
+        unless %i[ttc otc dfont].include?(format)
+          raise ArgumentError, "Invalid format: #{format}. Must be :ttc, :otc, or :dfont"
+        end
+      end
+
+      # Validate TTC compatibility
+      #
+      # Per OpenType spec: TTC = TrueType outlines ONLY
+      # "CFF rasterizer does not currently support TTC files"
+      #
+      # @param fonts [Array] Fonts
+      # @raise [Error] if incompatible
+      def validate_ttc!(fonts)
+        fonts.each_with_index do |font, index|
+          # Check for web fonts
+          if web_font?(font)
+            raise Error,
+                  "Font #{index} is a web font (WOFF/WOFF2). " \
+                  "Web fonts cannot be packed into collections."
+          end
+
+          # Check for TrueType outline format
+          unless truetype_font?(font)
+            raise Error,
+                  "Font #{index} is not TrueType. " \
+                  "TTC requires TrueType fonts only (per OpenType spec)."
+          end
+        end
+      end
+
+      # Validate OTC compatibility
+      #
+      # Per OpenType 1.8: OTC for CFF collections
+      # Fontisan extension: Also allows mixed TTF+OTF for flexibility
+      #
+      # @param fonts [Array] Fonts
+      # @raise [Error] if incompatible
+      def validate_otc!(fonts)
+        has_cff = false
+
+        fonts.each_with_index do |font, index|
+          # Check for web fonts
+          if web_font?(font)
+            raise Error,
+                  "Font #{index} is a web font (WOFF/WOFF2). " \
+                  "Web fonts cannot be packed into collections."
+          end
+
+          # Track if any font has CFF
+          has_cff = true if cff_font?(font)
+        end
+
+        # OTC should have at least one CFF font
+        unless has_cff
+          raise Error,
+                "OTC requires at least one CFF/OpenType font. " \
+                "All fonts are TrueType - use TTC instead."
+        end
+      end
+
+      # Validate dfont compatibility
+      #
+      # Apple dfont suitcase: Any SFNT fonts OK (TTF, OTF, or mixed)
+      # dfont stores complete Mac resources (FOND, NFNT, sfnt)
+      #
+      # @param fonts [Array] Fonts
+      # @raise [Error] if incompatible
+      def validate_dfont!(fonts)
+        fonts.each_with_index do |font, index|
+          # Only check for web fonts - dfont accepts any SFNT
+          if web_font?(font)
+            raise Error,
+                  "Font #{index} is a web font (WOFF/WOFF2). " \
+                  "Web fonts cannot be packed into dfont."
+          end
+        end
+      end
+
+      # Get TTC compatibility issues
+      #
+      # @param fonts [Array] Fonts
+      # @return [Array<String>] Issues
+      def ttc_issues(fonts)
+        issues = []
+
+        fonts.each_with_index do |font, index|
+          if web_font?(font)
+            issues << "Font #{index} is WOFF/WOFF2 (not allowed in collections)"
+          elsif !truetype_font?(font)
+            issues << "Font #{index} is not TrueType (TTC requires TrueType only)"
+          end
+        end
+
+        issues
+      end
+
+      # Get OTC compatibility issues
+      #
+      # @param fonts [Array] Fonts
+      # @return [Array<String>] Issues
+      def otc_issues(fonts)
+        issues = []
+        has_cff = false
+
+        fonts.each_with_index do |font, index|
+          if web_font?(font)
+            issues << "Font #{index} is WOFF/WOFF2 (not allowed in collections)"
+          end
+          has_cff = true if cff_font?(font)
+        end
+
+        unless has_cff
+          issues << "OTC requires at least one CFF font (all fonts are TrueType)"
+        end
+
+        issues
+      end
+
+      # Get dfont compatibility issues
+      #
+      # @param fonts [Array] Fonts
+      # @return [Array<String>] Issues
+      def dfont_issues(fonts)
+        issues = []
+
+        fonts.each_with_index do |font, index|
+          if web_font?(font)
+            issues << "Font #{index} is WOFF/WOFF2 (not allowed in dfont)"
+          end
+        end
+
+        issues
+      end
+
+      # Check if font is a web font
+      #
+      # @param font [Object] Font object
+      # @return [Boolean] true if WOFF or WOFF2
+      def web_font?(font)
+        font.class.name.include?("Woff")
+      end
+
+      # Check if font is TrueType
+      #
+      # @param font [Object] Font object
+      # @return [Boolean] true if TrueType
+      def truetype_font?(font)
+        return false unless font.respond_to?(:has_table?)
+
+        font.has_table?("glyf")
+      end
+
+      # Check if font is CFF/OpenType
+      #
+      # @param font [Object] Font object
+      # @return [Boolean] true if CFF
+      def cff_font?(font)
+        return false unless font.respond_to?(:has_table?)
+
+        font.has_table?("CFF ") || font.has_table?("CFF2")
+      end
+    end
+  end
+end