fontisan 0.2.7 → 0.2.9

data/Gemfile

@@ -6,7 +6,7 @@ source "https://rubygems.org"
 gemspec
 
 gem "canon", "~> 0.1.3"
-gem "openssl"
+gem "openssl", "~> 3.0"
 gem "rake"
 gem "rspec"
 gem "rubocop"

data/README.adoc

@@ -56,40 +56,52 @@ gem install fontisan
 
 == Features
 
+Color fonts and collections::
+* Color font support: COLR/CPAL layered glyphs, sbix bitmap glyphs, and SVG table (see link:docs/COLOR_FONTS.adoc[Color Fonts Guide])
+* Font collection validation with per-font reporting (see link:docs/COLLECTION_VALIDATION.adoc[Collection Validation Guide])
+
+Font analysis and information::
 * Bidirectional font hint conversion (see link:docs/FONT_HINTING.adoc[Font Hinting Guide])
 * Extract comprehensive font metadata (name, version, designer, license, etc.)
+* Brief mode for fast font indexing (5x faster, metadata-only loading)
 * List OpenType tables with checksums and offsets
 * Extract glyph names from post table
 * Display Unicode codepoint to glyph index mappings
 * Analyze variable font axes and named instances
-* Generate static font instances from variable fonts
 * Display optical size information
 * List supported scripts from GSUB/GPOS tables
 * List OpenType features (ligatures, kerning, etc.) by script
 * Dump raw binary table data for analysis
+
+Font operations::
+* Generate static font instances from variable fonts
 * Font subsetting with multiple profiles (PDF, web, minimal)
-* Font validation with multiple severity levels
-* Collection management (pack/unpack TTC/OTC files with table deduplication)
-* Support for TTF, OTF, TTC, OTC font formats (production ready)
-* Apple legacy font support: 'true' signature TrueType fonts and dfont (Data Fork Font) format
-* WOFF format support (reading complete, writing functional, pending full integration)
-* WOFF2 format support (reading complete with table transformations, writing planned)
+* Font validation framework with multiple profiles (indexability, usability, production, web, spec_compliance) (see link:docs/VALIDATION.adoc[Validation Guide])
+* Collection management (pack/unpack TTC/OTC/dfont files with table deduplication)
+
+Font format support::
+* TTF, OTF, TTC, OTC font formats (production ready)
+* WOFF/WOFF2 format support with reading, writing, and conversion (see link:docs/WOFF_WOFF2_FORMATS.adoc[WOFF/WOFF2 Guide])
+* Apple legacy font support: 'true' signature TrueType fonts and dfont format (see link:docs/APPLE_LEGACY_FONTS.adoc[Apple Legacy Fonts Guide])
 * SVG font generation (complete)
-* TTX/YAML/JSON export (complete)
-* Command-line interface with 18 commands
-* Ruby library API for programmatic access
-* Structured output in YAML, JSON, and text formats
-* Universal outline model for format-agnostic glyph representation (complete)
+
+Font engineering::
+* Universal outline model for format-agnostic glyph representation
 * CFF CharString encoding/decoding (complete)
 * CFF INDEX structure building (complete)
 * CFF DICT structure building (complete)
 * TrueType curve converter for bi-directional quadratic/cubic conversion (complete)
 * Compound glyph decomposition with transformation support (complete)
 * CFF subroutine optimization for space-efficient OTF generation (preview mode)
-* Various loading modes for high-performance font indexing (5x faster)
 * Bidirectional hint conversion (TrueType ↔ PostScript) with validation (complete)
 * CFF2 variable font support for PostScript hint conversion (complete)
 
+Export and interfaces::
+* TTX/YAML/JSON export (complete)
+* Command-line interface with 18 commands
+* Ruby library API for programmatic access
+* Structured output in YAML, JSON, and text formats
+
 
 == Font information
 
@@ -1034,26 +1046,19 @@ structures, usability, instructions, and glyphs.
 
 === Predefined profiles
 
-Fontisan includes several predefined validation profiles for common use cases:
+Fontisan includes validation profiles for different use cases:
 
-`indexability`:: Fast validation for font discovery and indexing (< 50ms). Uses
-BasicValidator with 8 essential checks. Loading mode: metadata.
+`indexability`:: Fast font discovery and indexing (~5x faster, 8 checks, metadata-only)
 
-`usability`:: Basic usability for font installation. Uses FontBookValidator with
-26 checks including macOS Font Book compatibility. Loading mode: full.
+`usability`:: Font installation compatibility (26 checks, macOS Font Book focused)
 
-`production`:: Comprehensive quality checks for production fonts (default
-profile). Uses OpenTypeValidator with 36 checks for OpenType spec compliance.
-Loading mode: full.
+`production`:: Comprehensive production quality (36 checks, OpenType spec compliance - default)
 
-`web`:: Web font embedding and optimization validation. Uses WebFontValidator
-with 18 checks for web deployment. Loading mode: full.
+`web`:: Web font embedding readiness (18 checks for web deployment)
 
-`spec_compliance`:: Full OpenType specification compliance with detailed checks.
-Uses OpenTypeValidator with info-level severity for comprehensive analysis.
-Loading mode: full.
+`spec_compliance`:: Full OpenType specification compliance (detailed analysis mode)
 
-`default`:: Alias for the production profile.
+`default`:: Alias for the production profile
 
 
 === Command-line usage
@@ -1154,6 +1159,80 @@ production, web, spec_compliance, default)
 
 -e, --exclude CHECKS:: Exclude specific checks (comma-separated list)
 
+=== Collection validation
+
+The `validate` command automatically detects and validates font collections (TTC, OTC, dfont).
+When validating a collection, fontisan validates all fonts in the collection and displays
+per-font results with an overall summary.
+
+.Validation profiles with collections
+[example]
+====
+All validation profiles work with font collections. The selected profile determines:
+
+* **Which tables are loaded** - metadata vs full mode
+* **Which checks are performed** - number and type of validations
+* **Performance characteristics** - indexability is ~5x faster than production
+
+For large collections (CJK fonts with 30+ fonts), use the `indexability` profile for fast
+validation when scanning for font discovery, or `production` for comprehensive quality
+checks.
+
+[source,shell]
+----
+# Quick validation for indexing (metadata mode, 8 checks, ~5x faster)
+$ fontisan validate /path/to/font.ttc -t indexability
+
+# Comprehensive validation (full mode, 37 checks)
+$ fontisan validate /path/to/font.ttc -t production
+
+# Web font readiness validation
+$ fontisan validate /path/to/font.ttc -t web
+----
+
+The collection validation output includes:
+
+* *Collection header* - Path, type, and number of fonts
+* *Summary* - Total errors, warnings, and info across all fonts
+* *Per-font sections* - Individual validation results for each font with:
+** Font index and name
+** Font path in `collection.ttc:index` format
+** Individual font status (VALID/INVALID/VALID_WITH_WARNINGS)
+** Font-specific errors and warnings
+** Exit codes* - For collections, uses the "worst" status across all fonts:
+** 0 = All fonts valid
+** 2 = Any font has fatal errors
+** 3 = Any font has errors (and no fatal)
+** 4 = Any font has warnings (and no errors)
+** 5 = Any font has info issues (and no errors or warnings)
+====
+
+.Validate a font collection
+[example]
+====
+[source,shell]
+----
+$ fontisan validate /path/to/font.ttc
+Collection: /path/to/font.ttc
+Type: TTC
+Fonts: 4
+
+Summary:
+  Total Errors: 14
+  Total Warnings: 8
+  Total Info: 0
+
+=== Font 0: Lucida Grande ===
+Font: /path/to/font.ttc:0
+Status: INVALID
+...
+
+=== Font 1: Lucida Grande Bold ===
+Font: /path/to/font.ttc:1
+Status: INVALID
+...
+----
+====
 
 === Ruby API usage
 

data/Rakefile

@@ -8,6 +8,7 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+# rubocop:disable Metrics/BlockLength
 namespace :fixtures do
   # Load centralized fixture configuration
   require_relative "spec/support/fixture_fonts"
@@ -99,8 +100,13 @@ namespace :fixtures do
     end
   end
 
+  # Compute download task prerequisites (marker files for non-skipped fonts)
+  download_prerequisites = fonts.values.reject do |config|
+    config[:skip_download]
+  end.map { |config| config[:marker] }
+
   desc "Download all test fixture fonts"
-  task download: fonts.values.reject { |config| config[:skip_download] }.map { |config| config[:marker] }
+  task download: download_prerequisites
 
   desc "Clean downloaded fixtures"
   task :clean do
@@ -112,17 +118,16 @@ namespace :fixtures do
           FileUtils.rm_f(config[:marker])
           puts "[fixtures:clean] Removed #{config[:marker]}"
         end
-      else
+      elsif File.exist?(config[:target_dir])
         # For archives, delete the entire target directory
-        if File.exist?(config[:target_dir])
-          puts "[fixtures:clean] Removing #{config[:target_dir]}..."
-          FileUtils.rm_rf(config[:target_dir])
-          puts "[fixtures:clean] Removed #{config[:target_dir]}"
-        end
+        puts "[fixtures:clean] Removing #{config[:target_dir]}..."
+        FileUtils.rm_rf(config[:target_dir])
+        puts "[fixtures:clean] Removed #{config[:target_dir]}"
       end
     end
   end
 end
+# rubocop:enable Metrics/BlockLength
 
 # RSpec task depends on fixtures
 RSpec::Core::RakeTask.new(spec: "fixtures:download")

data/benchmark/variation_quick_bench.rb

@@ -18,7 +18,7 @@ puts "Font: #{FONT_PATH}"
 puts
 
 # Test coordinates
-coords = Array.new(4) { |i| { "wght" => 300 + i * 200 } }
+coords = Array.new(4) { |i| { "wght" => 300 + (i * 200) } }
 puts "Generating #{coords.size} instances"
 puts
 

data/docs/APPLE_LEGACY_FONTS.adoc

@@ -0,0 +1,173 @@
+= Apple Legacy Font Format Support
+
+== General
+
+Fontisan provides support for Apple's legacy font formats that predate modern
+OpenType standards:
+
+* **'true' signature TrueType fonts** - Older Mac fonts with 'true' sfnt version
+* **dfont (Data Fork Font)** - Mac suitcase format with fonts in data fork
+
+These formats require special handling due to their unique structures and
+historical platform-specific conventions.
+
+=== 'true' signature TrueType fonts
+
+Traditional TrueType fonts use 'true' (0x74727565) as the SFNT version instead
+of the modern 0x00010000. These were common on classic Mac OS.
+
+[source,shell]
+----
+$ fontisan info legacy_font.ttf
+
+Font type:                TrueType (Not Variable)
+SFNT Version:             'true' (legacy)
+Family:                   Legacy Font
+...
+
+Detection:
+  Fontisan automatically detects 'true' signature fonts
+  Treats them as standard TrueType for all operations
+  Preserves signature format when writing
+----
+
+=== dfont (Data Fork Font) format
+
+The dfont format stores complete Mac font suitcases in the data fork, supporting
+multiple fonts in a single file with resource-fork style structure.
+
+[source,shell]
+----
+$ fontisan ls family.dfont
+
+Font 0: Arial
+  Family: Arial
+  Subfamily: Regular
+
+Font 1: Arial
+  Family: Arial
+  Subfamily: Bold
+
+Font 2: Arial
+  Family: Arial
+  Subfamily: Italic
+----
+
+.dfont structure
+[example]
+====
+[source,text]
+----
+dfont format structure:
+
+Data Fork Map:
+  Resource data: Contains all font resources
+  Resource map: Index of resources by type and ID
+  Postscript names: Font name mapping
+
+Supported fonts in dfont:
+  - TrueType fonts ('true' signature)
+  - OpenType fonts (CFF or TrueType outlines)
+  - Mixed formats in single dfont
+
+Features:
+  - Automatic resource fork extraction
+  - Font list with metadata
+  - Extract individual fonts by index
+  - Unpack all fonts to directory
+  - Validate fonts within dfont
+====
+----
+
+=== Working with dfont files
+
+==== List fonts in dfont
+
+[source,shell]
+----
+$ fontisan ls family.dfont
+
+Font 0: Arial Regular
+  Family: Arial
+  Subfamily: Regular
+  PostScript: Arial
+
+Font 1: Arial Bold
+  Family: Arial
+  Subfamily: Bold
+  PostScript: Arial-Bold
+----
+
+==== Show dfont info
+
+[source,shell]
+----
+$ fontisan info family.dfont
+
+Collection: family.dfont
+Type: dfont
+Fonts: 3
+
+Font 0 (offset: 256):
+  Font type:                TrueType (Not Variable)
+  Family:                   Arial
+  Subfamily:                Regular
+  ...
+----
+
+==== Extract fonts from dfont
+
+[source,shell]
+----
+# Extract all fonts
+$ fontisan unpack family.dfont extracted_fonts/
+
+# Extract specific font
+$ fontisan unpack family.dfont --font-index 0 Arial.ttf
+----
+
+==== Validate dfont
+
+[source,shell]
+----
+$ fontisan validate family.dfont -t indexability
+
+Collection: family.dfont
+Type: dfont
+Fonts: 3
+
+Summary:
+  Total Errors: 0
+  Total Warnings: 2
+
+=== Font 0: Arial Regular ===
+Font: family.dfont:0
+Status: VALID_WITH_WARNINGS
+...
+----
+
+=== Ruby API for dfont
+
+[source,ruby]
+----
+require 'fontisan'
+
+# Load dfont collection
+dfont = Fontisan::FontLoader.load('family.dfont')
+
+# Access as collection
+puts "Font count: #{dfont.font_count}"
+File.open('family.dfont', 'rb') do |io|
+  fonts = dfont.extract_fonts(io)
+  fonts.each_with_index do |font, i|
+    puts "Font #{i}: #{font.family_name}"
+  end
+end
+
+# Extract specific font
+font = Fontisan::FontLoader.load('family.dfont', font_index: 0)
+
+# Validate dfont
+report = Fontisan.validate('family.dfont')
+puts report.valid?  # => true/false
+----

data/docs/COLLECTION_VALIDATION.adoc

@@ -0,0 +1,143 @@
+= Font Collection Validation
+
+== General
+
+Fontisan provides validation support for font collections (TTC, OTC, dfont),
+enabling quality assurance across multiple fonts in a single file.
+
+Collection validation ensures all fonts in a collection meet quality standards
+while providing per-font and aggregate reporting.
+
+== Collection validation output
+
+When validating a collection, Fontisan displays:
+
+* *Collection header* - Path, type, and number of fonts
+* *Summary* - Total errors, warnings, and info across all fonts
+* *Per-font sections* - Individual validation results for each font with:
+  ** Font index and name
+  ** Font path in `collection.ttc:index` format
+  ** Individual font status (VALID/INVALID/VALID_WITH_WARNINGS)
+  ** Font-specific errors and warnings
+
+.Using the CLI to validate a font collection
+[example]
+====
+[source,shell]
+----
+$ fontisan validate /path/to/font.ttc
+
+Collection: /path/to/font.ttc
+Type: TTC
+Fonts: 4
+
+Summary:
+  Total Errors: 14
+  Total Warnings: 8
+  Total Info: 0
+
+=== Font 0: Lucida Grande ===
+Font: /path/to/font.ttc:0
+Status: INVALID
+
+Errors:
+  name_table.family_name_present - Family name is empty
+  head_table.valid_magic - Invalid magic number
+
+Warnings:
+  os2_table.valid_version - Version 5 requires Windows 10+
+
+=== Font 1: Lucida Grande Bold ===
+Font: /path/to/font.ttc:1
+Status: VALID
+...
+----
+====
+
+== Validation profiles with collections
+
+All validation profiles work with font collections. The selected profile determines:
+
+* **Which tables are loaded** - metadata vs full mode
+* **Which checks are performed** - number and type of validations
+* **Performance characteristics** - indexability is ~5x faster than production
+
+.Using validation profiles with collections
+[example]
+====
+[source,shell]
+----
+# Quick validation for indexing (metadata mode, 8 checks, ~5x faster)
+$ fontisan validate /path/to/font.ttc -t indexability
+
+# Comprehensive validation (full mode, 37 checks)
+$ fontisan validate /path/to/font.ttc -t production
+
+# Web font readiness validation
+$ fontisan validate /path/to/font.ttc -t web
+----
+====
+
+== Collection validation exit codes
+
+For collections, the validation command uses the "worst" status across all fonts:
+
+* **0** = All fonts valid
+* **2** = Any font has fatal errors
+* **3** = Any font has errors (and no fatal)
+* **4** = Any font has warnings (and no errors)
+* **5** = Any font has info issues (and no errors or warnings)
+
+.Checking collection validation exit codes
+[example]
+====
+[source,shell]
+----
+$ fontisan validate font.ttc -S -R
+
+Collection: font.ttc
+Type: TTC
+Fonts: 3
+
+Summary:
+  Total Errors: 2
+  Total Warnings: 5
+
+$ echo $?
+3  # Exit code 3 indicates errors found
+----
+====
+
+== Ruby API for collection validation
+
+.Using the Ruby API for collection validation
+[example]
+====
+[source,ruby]
+----
+require 'fontisan'
+
+# Validate collection
+report = Fontisan.validate('font.ttc', profile: :production)
+
+# Check overall status
+puts report.overall_status  # "valid", "valid_with_warnings", "invalid"
+
+# Access per-font reports
+report.font_reports.each_with_index do |font_report, i|
+  puts "Font #{i}: #{font_report.font_name}"
+  puts "  Status: #{font_report.report.status}"
+  puts "  Errors: #{font_report.report.summary.errors}"
+  puts "  Warnings: #{font_report.report.summary.warnings}"
+end
+
+# Get aggregate statistics
+puts "Total fonts: #{report.num_fonts}"
+
+# Count valid/invalid fonts (requires iteration)
+valid_count = report.font_reports.count { |fr| fr.report.valid? }
+invalid_count = report.font_reports.count { |fr| !fr.report.valid? }
+puts "Valid fonts: #{valid_count}"
+puts "Invalid fonts: #{invalid_count}"
+----
+====

data/docs/COLOR_FONTS.adoc

@@ -0,0 +1,127 @@
+= Color Font Support
+
+== General
+
+Fontisan provides support for color fonts through multiple formats:
+
+* **COLR/CPAL** - OpenType color layered glyphs (SVG-like layering in font)
+* **sbix** - Apple color bitmap glyphs (embedded raster images)
+* **SVG** - OpenType SVG color glyphs (embedded SVG vector graphics)
+
+Color fonts enable rich typography with gradients, images, and artistic effects
+beyond standard outline fonts.
+
+=== COLR/CPAL color layered glyphs
+
+The COLR table defines color layers using base glyphs and paint layers,
+with the CPAL table defining color palettes.
+
+[source,shell]
+----
+$ fontisan tables FONT.ttf --format yaml | grep -A 50 "tag: COLR"
+----
+
+.COLR table structure
+[example]
+====
+[source,yaml]
+----
+---
+tag: COLR
+version: 0
+num_base_glyphs: 15
+num_layers: 47
+num_palettes: 1
+color_records: 8
+
+Base glyphs:
+  - base_glyph: emoji_smile
+    layers:
+      - glyph: emoji_smile_layer0
+        palette_index: 1
+        color_index: 0
+      - glyph: emoji_smile_layer1
+        palette_index: 1
+        color_index: 1
+----
+====
+
+=== sbix color bitmap glyphs
+
+Apple's sbix table embeds raster images (PNG, JPG) for color glyphs.
+Each glyph can have multiple bitmap strikes at different sizes.
+
+[source,shell]
+----
+$ fontisan tables FONT.ttf | grep -A 20 "tag: sbix"
+----
+
+.sbix structure
+[example]
+====
+[source,text]
+----
+  sbix        245892 bytes  (offset: 542992, checksum: 0x12345678)
+
+Strikes:
+  Strike 0: 72 PPI
+    Bitmaps: 150 glyphs
+    Format: PNG
+    Glyph 1 (emoji_smile): 128x128 pixels, 8.2 KB
+    Glyph 2 (emoji_heart): 128x128 pixels, 7.8 KB
+----
+====
+
+=== SVG table color glyphs
+
+The SVG table contains inline SVG graphics for color glyphs, supporting
+gradients, transparency, and complex vector artwork.
+
+[source,shell]
+----
+$ fontisan dump-table FONT.ttf SVG > svg_content.svg
+----
+
+.SVG table structure
+[example]
+====
+[source,text]
+----
+  svg         45678 bytes  (offset: 788760, checksum: 0xABCDEF01)
+
+SVG Documents: 12
+  Glyph 1 (emoji_flag_us): 1.2 KB
+  Glyph 2 (emoji_heart): 0.8 KB
+  Glyph 3 (gradient_icon): 2.1 KB
+----
+====
+
+=== Ruby API for color fonts
+
+Access color font data through the Ruby API.
+
+[source,ruby]
+----
+require 'fontisan'
+
+font = Fontisan::FontLoader.load('color_font.ttf')
+
+# Access COLR/CPAL data
+colr = font.table('COLR')
+cpal = font.table('CPAL')
+
+puts "Base glyphs: #{colr.num_base_glyph_records}"
+puts "Palettes: #{cpal.num_palettes}"
+
+# Access sbix strikes
+sbix = font.table('sbix')
+sbix.strikes.each do |strike|
+  puts "Strike: #{strike[:ppi]} PPI, #{strike[:num_glyphs]} glyphs"
+end
+
+# Access SVG data
+svg = font.table('SVG')
+svg.document_records.each do |record|
+  puts "Glyphs #{record.start_glyph_id}-#{record.end_glyph_id}: #{record.svg_doc_length} bytes"
+end
+----