fontisan 0.1.0 → 0.2.0

data/lib/fontisan/config/conversion_matrix.yml

@@ -0,0 +1,212 @@
+# Font Format Conversion Matrix
+#
+# This file defines the supported font format conversions for Fontisan.
+# Each conversion specifies a source format ('from') and target format ('to').
+#
+# Format identifiers:
+# - ttf: TrueType Font (with glyf/loca tables)
+# - otf: OpenType Font with CFF outlines (with CFF table)
+# - woff: Web Open Font Format (not yet implemented)
+# - woff2: Web Open Font Format 2 (implemented in Phase 2)
+# - svg: SVG Font (implemented in Phase 2)
+#
+# Phase 1 (Milestone 1.3): Basic conversions
+# - Same format (copy/optimize): ttf→ttf, otf→otf
+# - Outline conversion: ttf↔otf (foundation implemented)
+#
+# Phase 2 (Milestone 2.1): Web font formats
+# - WOFF2 compression: ttf to woff2, otf to woff2
+#
+# Phase 2 (Milestone 2.2): SVG font generation
+# - SVG export: ttf to svg, otf to svg
+#
+# Future phases:
+# - Phase 3: Variable font conversions
+
+conversions:
+  # Same-format conversions (copy/optimize)
+  - from: ttf
+    to: ttf
+    strategy: table_copier
+    description: "Copy TrueType font with table optimization"
+    status: implemented
+
+  - from: otf
+    to: otf
+    strategy: table_copier
+    description: "Copy OpenType/CFF font with table optimization"
+    status: implemented
+
+  # Outline format conversions
+  - from: ttf
+    to: otf
+    strategy: outline_converter
+    description: "Convert TrueType outlines to CFF format"
+    status: foundation
+    notes: >
+      Foundation implemented. Full conversion requires complete CFF table
+      generation including CharString encoding, DICT structures, and
+      charset/encoding tables.
+
+  - from: otf
+    to: ttf
+    strategy: outline_converter
+    description: "Convert CFF outlines to TrueType format"
+    status: foundation
+    notes: >
+      Foundation implemented. Full conversion requires complete glyf/loca
+      table generation including cubic-to-quadratic curve conversion and
+      proper TrueType glyph structure encoding.
+
+  # Phase 2 conversions (Milestone 2.1) - WOFF2
+  - from: ttf
+    to: woff2
+    strategy: woff2_encoder
+    description: "Compress TrueType to WOFF2 format with Brotli"
+    status: implemented
+    notes: >
+      WOFF2 encoding with Brotli compression. Table transformations
+      are architectural placeholders for future optimization.
+
+  - from: otf
+    to: woff2
+    strategy: woff2_encoder
+    description: "Compress OpenType/CFF to WOFF2 format with Brotli"
+    status: implemented
+    notes: >
+      WOFF2 encoding with Brotli compression. Table transformations
+      are architectural placeholders for future optimization.
+
+  # Phase 2 conversions (Milestone 2.3) - WOFF
+  # NOTE: Temporarily disabled until WOFF writer bugs are fixed
+  # - from: ttf
+  #   to: woff
+  #   strategy: woff_writer
+  #   description: "Compress TrueType to WOFF format with zlib"
+  #   status: implemented
+  #   notes: >
+  #     WOFF 1.0 encoding with zlib compression. Supports optional metadata
+  #     and private data blocks. Individual table compression for optimal
+  #     file size reduction.
+
+  # - from: otf
+  #   to: woff
+  #   strategy: woff_writer
+  #   description: "Compress OpenType/CFF to WOFF format with zlib"
+  #   status: implemented
+  #   notes: >
+  #     WOFF 1.0 encoding with zlib compression. Supports optional metadata
+  #     and private data blocks. Individual table compression for optimal
+  #     file size reduction.
+
+  # Reverse WOFF conversions (WOFF → TTF/OTF)
+  - from: woff
+    to: ttf
+    strategy: woff_reader
+    description: "Extract TrueType from WOFF format"
+    status: implemented
+    notes: >
+      WOFF decompression with zlib. Preserves all font data and metadata.
+      Automatically detects font flavor from WOFF header.
+
+  - from: woff
+    to: otf
+    strategy: woff_reader
+    description: "Extract OpenType/CFF from WOFF format"
+    status: implemented
+    notes: >
+      WOFF decompression with zlib. Preserves all font data and metadata.
+      Automatically detects font flavor from WOFF header.
+
+  # Phase 2 conversions (Milestone 2.2) - SVG
+  - from: ttf
+    to: svg
+    strategy: svg_generator
+    description: "Generate SVG font from TrueType"
+    status: implemented
+    notes: >
+      SVG font generation with full glyph outline extraction and coordinate
+      transformation. Note: SVG fonts are deprecated in favor of WOFF2, but
+      useful for fallback, conversion, and inspection purposes.
+
+  - from: otf
+    to: svg
+    strategy: svg_generator
+    description: "Generate SVG font from OpenType/CFF"
+    status: implemented
+    notes: >
+      SVG font generation with full glyph outline extraction and coordinate
+      transformation. Note: SVG fonts are deprecated in favor of WOFF2, but
+      useful for fallback, conversion, and inspection purposes.
+
+# Conversion compatibility matrix
+#
+# This section documents which source features are preserved in conversions.
+# Not all features can be preserved across format boundaries.
+#
+compatibility:
+  ttf_to_otf:
+    preserves:
+      - glyph_outlines
+      - font_metrics
+      - name_table
+      - layout_features
+      - kerning
+    limitations:
+      - quadratic_to_cubic_approximation: >
+          TrueType quadratic curves are converted to CFF cubic curves.
+          The conversion is mathematically exact.
+      - hinting_loss: >
+          TrueType hinting instructions are not converted to CFF hints.
+
+  otf_to_ttf:
+    preserves:
+      - glyph_outlines
+      - font_metrics
+      - name_table
+      - layout_features
+      - kerning
+    limitations:
+      - cubic_to_quadratic_approximation: >
+          CFF cubic curves must be approximated as TrueType quadratic curves.
+          Multiple quadratic curves may be needed for accuracy.
+      - hinting_loss: >
+          CFF hints are not converted to TrueType hinting instructions.
+
+  same_format:
+    preserves:
+      - all_tables
+      - all_features
+      - exact_outline_data
+    benefits:
+      - table_reordering: Tables are written in optimal order
+      - checksum_correction: All checksums are recalculated
+      - padding_normalization: Table padding is normalized
+
+  to_woff2:
+    preserves:
+      - glyph_outlines
+      - font_metrics
+      - all_tables
+      - layout_features
+    benefits:
+      - brotli_compression: Excellent compression ratio for web delivery
+      - smaller_file_size: Typically 30-50% smaller than TTF/OTF
+    limitations:
+      - web_only: Primarily for web font delivery
+      - browser_support: Not all browsers support WOFF2
+
+  to_svg:
+    preserves:
+      - glyph_outlines: Outlines converted to SVG paths
+      - font_metrics: Basic metrics in font-face element
+      - unicode_mappings: Unicode to glyph associations
+    limitations:
+      - deprecated_format: SVG fonts deprecated in favor of WOFF2
+      - limited_browser_support: Mainly Safari
+      - no_hinting: Hinting information not preserved
+      - no_advanced_features: Complex layout features not supported
+    use_cases:
+      - fallback: Emergency fallback for very old browsers
+      - conversion: Intermediate format for font conversion workflows
+      - inspection: Easy-to-read format for font inspection

data/lib/fontisan/config/export_settings.yml

@@ -0,0 +1,66 @@
+
+# Font Export Settings
+#
+# Configuration for font export to YAML/JSON formats
+
+# Default export settings
+defaults:
+  binary_format: hex  # hex or base64
+  pretty: true
+  include_metadata: true
+
+# Table export strategies
+# - parsed: Full Lutaml::Model serialization
+# - binary: Store as hex/base64
+# - mixed: Summary + binary data
+table_strategies:
+  parsed:
+    - head
+    - hhea
+    - maxp
+    - post
+    - OS/2
+    - name
+    - fvar
+    - HVAR
+    - VVAR
+    - MVAR
+    - cvar
+    - gvar
+
+  binary:
+    - cvt
+    - fpgm
+    - prep
+    - gasp
+    - DSIG
+    - GDEF
+    - GPOS
+    - GSUB
+
+  mixed:
+    - glyf
+    - loca
+    - cmap
+    - CFF
+    - hmtx
+    - vmtx
+
+# Binary data encoding preferences per table
+binary_encoding:
+  default: hex
+  DSIG: base64  # Signatures are typically base64
+
+# Pretty-print settings
+pretty_print:
+  yaml:
+    line_width: 80
+    indent: 2
+  json:
+    indent: 2
+    space: " "
+
+# Export optimization
+optimization:
+  compress_binary: false  # Compress binary data (future)
+  deduplicate_tables: false  # Deduplicate identical tables (future)

data/lib/fontisan/config/subset_profiles.yml

@@ -0,0 +1,100 @@
+# Font Subsetting Profiles Configuration
+#
+# This file defines predefined subsetting profiles that specify which
+# font tables should be included in the subset. Each profile is optimized
+# for a specific use case.
+#
+# Profile Format:
+#   profile_name:
+#     description: Human-readable description of the profile
+#     tables: Array of table tags to include in the subset
+#
+# Common Table Tags:
+#   - cmap: Character to glyph mapping
+#   - head: Font header
+#   - hhea: Horizontal header
+#   - hmtx: Horizontal metrics
+#   - maxp: Maximum profile
+#   - name: Naming table
+#   - post: PostScript information
+#   - loca: Glyph location index (TrueType)
+#   - glyf: Glyph data (TrueType)
+#   - OS/2: OS/2 and Windows metrics
+#   - CFF : Compact Font Format (OpenType)
+#   - GSUB: Glyph Substitution
+#   - GPOS: Glyph Positioning
+#   - GDEF: Glyph Definition
+
+# PDF Profile: Minimal tables required for PDF embedding
+pdf:
+  description: Minimal tables required for PDF font embedding
+  tables:
+    - cmap
+    - head
+    - hhea
+    - hmtx
+    - maxp
+    - name
+    - post
+    - loca
+    - glyf
+
+# Web Profile: Tables required for web font usage
+web:
+  description: Tables required for web browsers and modern rendering
+  tables:
+    - cmap
+    - head
+    - hhea
+    - hmtx
+    - maxp
+    - name
+    - OS/2
+    - post
+    - loca
+    - glyf
+    - GSUB
+    - GPOS
+
+# Minimal Profile: Absolute minimum tables for font rendering
+minimal:
+  description: Absolute minimum tables for basic font rendering
+  tables:
+    - cmap
+    - head
+    - hhea
+    - hmtx
+    - maxp
+    - name
+    - OS/2
+    - post
+
+# Full Profile: All standard tables (for comprehensive subsetting)
+full:
+  description: All standard TrueType/OpenType tables
+  tables:
+    - cmap
+    - head
+    - hhea
+    - hmtx
+    - maxp
+    - name
+    - OS/2
+    - post
+    - loca
+    - glyf
+    - cvt
+    - fpgm
+    - prep
+    - gasp
+    - GSUB
+    - GPOS
+    - GDEF
+    - BASE
+    - JSTF
+    - CFF
+    - CFF2
+    - VORG
+    - kern
+    - vhea
+    - vmtx

data/lib/fontisan/config/svg_settings.yml

@@ -0,0 +1,60 @@
+---
+# SVG Font Generation Settings
+#
+# Configuration for SVG font generation, following external configuration
+# principle. These settings control SVG output formatting and glyph selection.
+
+# Output formatting
+formatting:
+  # Pretty print XML with indentation
+  pretty_print: true
+  # Number of spaces for indentation
+  indent_spaces: 2
+  # Include XML declaration
+  xml_declaration: true
+
+# Coordinate precision
+coordinates:
+  # Number of decimal places for coordinates
+  decimal_places: 2
+  # Round coordinates to integers
+  round_to_integer: true
+
+# Glyph selection
+glyphs:
+  # Maximum number of glyphs to include (null = all)
+  max_glyphs: null
+  # Include .notdef glyph
+  include_notdef: true
+  # Include only glyphs with unicode mappings
+  unicode_only: false
+
+# Font metadata
+metadata:
+  # Include font-face element
+  include_font_face: true
+  # Include bounding box in font-face
+  include_bbox: true
+  # Include underline position/thickness
+  include_underline: true
+  # Include x-height and cap-height
+  include_heights: true
+
+# Default values for missing data
+defaults:
+  # Default advance width for missing-glyph
+  missing_glyph_advance: 500
+  # Default units per em
+  units_per_em: 1000
+  # Default ascent
+  ascent: 800
+  # Default descent
+  descent: -200
+
+# Limitations and warnings
+limitations:
+  # Note: SVG fonts are deprecated in favor of WOFF/WOFF2
+  # Limited browser support (mostly Safari)
+  # Useful for: fallback, conversion, inspection
+  # Modern web should use WOFF2
+  warn_deprecated: true

data/lib/fontisan/config/validation_rules.yml

@@ -0,0 +1,149 @@
+# Font Validation Rules Configuration
+#
+# This file defines validation rules for different font types and validation levels.
+# The rules determine which checks are performed and their severity thresholds.
+
+# Required tables for different font types
+required_tables:
+  # Tables required for all fonts
+  all:
+    - head
+    - name
+    - cmap
+    - maxp
+    - hhea
+    - hmtx
+    - post
+    - OS/2
+
+  # Additional tables required for TrueType fonts (.ttf)
+  truetype:
+    - glyf
+    - loca
+
+  # Additional tables required for OpenType/CFF fonts (.otf)
+  opentype_cff:
+    - CFF   # or CFF2 for CFF2 format
+
+  # Additional tables required for variable fonts
+  variable:
+    - fvar
+    - gvar  # For TrueType variable fonts
+    - HVAR  # Horizontal metrics variations (optional but recommended)
+    - MVAR  # Metrics variations (optional)
+
+# Validation levels define which checks to perform
+validation_levels:
+  # Strict: All checks must pass, no warnings allowed
+  strict:
+    check_required_tables: true
+    check_table_checksums: true
+    check_head_checksum_adjustment: true
+    check_glyph_consistency: true
+    check_cmap_references: true
+    check_hmtx_consistency: true
+    check_name_consistency: true
+    check_variable_consistency: true
+    check_table_offsets: true
+    check_table_ordering: false  # Not critical for correctness
+    allow_warnings: false
+    allow_info: true
+
+  # Standard: Most checks enabled, warnings allowed
+  standard:
+    check_required_tables: true
+    check_table_checksums: true
+    check_head_checksum_adjustment: true
+    check_glyph_consistency: true
+    check_cmap_references: true
+    check_hmtx_consistency: true
+    check_name_consistency: true
+    check_variable_consistency: true
+    check_table_offsets: true
+    check_table_ordering: false
+    allow_warnings: true
+    allow_info: true
+
+  # Lenient: Basic checks only, many warnings allowed
+  lenient:
+    check_required_tables: true
+    check_table_checksums: false  # Skip checksum validation
+    check_head_checksum_adjustment: false
+    check_glyph_consistency: true
+    check_cmap_references: false  # Skip cmap validation
+    check_hmtx_consistency: true
+    check_name_consistency: false
+    check_variable_consistency: false
+    check_table_offsets: true
+    check_table_ordering: false
+    allow_warnings: true
+    allow_info: true
+
+# Error messages templates
+error_messages:
+  missing_table: "Missing required table: %{table}"
+  invalid_table_checksum: "Table '%{table}' checksum mismatch (expected: %{expected}, got: %{actual})"
+  invalid_head_checksum: "Invalid head table checksum adjustment"
+  glyph_count_mismatch: "Glyph count mismatch: maxp=%{maxp}, actual=%{actual}"
+  invalid_cmap_reference: "cmap references non-existent glyph ID %{glyph_id}"
+  hmtx_count_mismatch: "hmtx entries (%{hmtx}) don't match glyph count (%{glyph_count})"
+  invalid_table_offset: "Table '%{table}' has invalid offset: %{offset}"
+  variable_table_missing: "Variable font missing required table: %{table}"
+  fvar_gvar_mismatch: "fvar axis count (%{fvar}) doesn't match gvar axis count (%{gvar})"
+
+# Warning messages templates
+warning_messages:
+  table_checksum_mismatch: "Table '%{table}' checksum mismatch"
+  suboptimal_table_order: "Tables not in optimal order for performance"
+  missing_optional_table: "Optional table '%{table}' not present (recommended for %{reason})"
+  name_inconsistency: "Name table inconsistency: %{issue}"
+  large_font_size: "Font file size (%{size} bytes) is unusually large"
+
+# Info messages templates
+info_messages:
+  optimization_opportunity: "Font could benefit from %{optimization}"
+  subsetting_recommended: "Font contains %{glyph_count} glyphs; subsetting may reduce size"
+  compression_recommended: "Font could benefit from WOFF2 compression"
+
+# Checksum validation settings
+checksum_validation:
+  # Magic number for checksum adjustment calculation
+  magic: 0xB1B0AFBA
+
+  # Tables exempt from checksum validation (some tables have dynamic content)
+  skip_tables:
+    - DSIG  # Digital signature table (changes with signing)
+
+# Consistency checks configuration
+consistency_checks:
+  # Maximum acceptable glyph ID for cmap validation
+  max_glyph_id_multiplier: 2.0  # Allow up to 2x maxp.numGlyphs for safety
+
+  # Minimum acceptable glyph count
+  min_glyph_count: 1
+
+  # Maximum acceptable glyph count (sanity check)
+  max_glyph_count: 65536
+
+# Structure validation settings
+structure_validation:
+  # Minimum valid offset (after header and directory)
+  min_table_offset: 12
+
+  # Table alignment requirement (4-byte alignment)
+  table_alignment: 4
+
+  # Maximum reasonable table size (100MB)
+  max_table_size: 104857600
+
+# Variable font specific validation
+variable_validation:
+  # Check that all required variation tables are consistent
+  check_axis_consistency: true
+
+  # Check that variation regions are valid
+  check_region_validity: true
+
+  # Check that deltas are within reasonable bounds
+  max_delta_value: 32767
+  min_delta_value: -32768

data/lib/fontisan/config/variable_settings.yml

@@ -0,0 +1,99 @@
+# Configuration for variable font delta application
+#
+# These settings control how deltas are calculated and applied when
+# instancing variable fonts at specific design space coordinates.
+
+# Delta Application Settings
+delta_application:
+  # Rounding mode for accumulated deltas
+  # Options: round, floor, ceil, truncate
+  rounding_mode: round
+
+  # Interpolation quality
+  # Options: fast, normal, high
+  interpolation_quality: normal
+
+  # Whether to validate coordinates against axis ranges
+  validate_coordinates: true
+
+  # Whether to clamp out-of-range coordinates
+  clamp_coordinates: true
+
+  # Minimum scalar threshold below which deltas are ignored
+  # (Performance optimization: regions with very low contribution)
+  min_scalar_threshold: 0.0001
+
+# Coordinate Normalization Settings
+coordinate_normalization:
+  # Whether to normalize coordinates to -1.0 to 1.0 range
+  normalize: true
+
+  # Default axis values if not specified
+  use_axis_defaults: true
+
+  # Precision for normalized values (decimal places)
+  normalized_precision: 6
+
+# Region Matching Settings
+region_matching:
+  # Algorithm: standard (OpenType spec compliant)
+  algorithm: standard
+
+  # Whether to use multi-axis region matching
+  multi_axis: true
+
+  # Cache region scalars for reuse
+  cache_scalars: true
+
+# Glyph Delta Processing
+glyph_deltas:
+  # Apply deltas to simple glyphs
+  apply_to_simple: true
+
+  # Apply deltas to compound glyphs
+  apply_to_compound: true
+
+  # Process phantom points (metrics)
+  process_phantom_points: true
+
+  # Number of phantom points (standard: 4)
+  phantom_point_count: 4
+
+# Metric Delta Processing
+metric_deltas:
+  # Apply horizontal metric deltas (HVAR)
+  apply_hvar: true
+
+  # Apply vertical metric deltas (VVAR)
+  apply_vvar: true
+
+  # Apply font-level metric deltas (MVAR)
+  apply_mvar: true
+
+  # Update dependent metrics automatically
+  update_dependent_metrics: true
+
+# Performance Settings
+performance:
+  # Parallel processing for multiple glyphs
+  parallel_processing: false
+
+  # Maximum number of threads (if parallel)
+  max_threads: 4
+
+  # Cache parsed variation tables
+  cache_variation_tables: true
+
+# Validation Settings
+validation:
+  # Validate variation table consistency
+  validate_tables: true
+
+  # Check for required tables
+  check_required_tables: true
+
+  # Validate coordinate ranges
+  validate_ranges: true
+
+  # Strict mode (fail on any error)
+  strict_mode: false