fontisan 0.2.13 → 0.2.16

data/docs/api/font-loader.md

@@ -0,0 +1,111 @@
+---
+title: FontLoader
+---
+
+# FontLoader
+
+Unified font loading with automatic format detection.
+
+## Overview
+
+`Fontisan::FontLoader` provides a unified interface for loading fonts in any supported format.
+
+## Class Methods
+
+### load(source)
+
+Load a font from file path or IO.
+
+```ruby
+# From file path
+font = Fontisan::FontLoader.load('font.ttf')
+font = Fontisan::FontLoader.load('font.otf')
+font = Fontisan::FontLoader.load('font.pfb')
+font = Fontisan::FontLoader.load('font.woff2')
+
+# From IO
+font = Fontisan::FontLoader.load(File.open('font.ttf'))
+
+# From string
+font = Fontisan::FontLoader.load(File.read('font.ttf', mode: 'rb'))
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| source | String, IO | File path, IO object, or binary data |
+
+**Returns:** SfntFont, Type1Font, or Collection
+
+**Raises:** Fontisan::FormatError if format is unsupported
+
+### detect_format(source)
+
+Detect font format without loading.
+
+```ruby
+format = Fontisan::FontLoader.detect_format('font.ttf')
+# => :ttf
+
+format = Fontisan::FontLoader.detect_format('font.otf')
+# => :otf
+
+format = Fontisan::FontLoader.detect_format('font.pfb')
+# => :type1
+```
+
+**Returns:** Symbol or nil
+
+## 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 |
+
+## Examples
+
+### Load with Error Handling
+
+```ruby
+begin
+  font = Fontisan::FontLoader.load(path)
+  puts "Loaded: #{font.family_name}"
+rescue Fontisan::FormatError => e
+  puts "Unsupported format: #{e.message}"
+rescue Errno::ENOENT => e
+  puts "File not found: #{path}"
+end
+```
+
+### Batch Loading
+
+```ruby
+fonts = Dir.glob('fonts/*.ttf').map do |path|
+  Fontisan::FontLoader.load(path)
+end
+
+puts "Loaded #{fonts.length} fonts"
+```
+
+### Detect and Load
+
+```ruby
+path = 'unknown.dat'
+
+format = Fontisan::FontLoader.detect_format(path)
+if format
+  puts "Detected format: #{format}"
+  font = Fontisan::FontLoader.load(path)
+else
+  puts "Unknown format"
+end
+```

data/docs/api/font-writer.md

@@ -0,0 +1,103 @@
+---
+title: FontWriter
+---
+
+# FontWriter
+
+Write fonts to various formats.
+
+## Overview
+
+`Fontisan::FontWriter` handles saving fonts to files in various formats.
+
+## Class Methods
+
+### write(font, path, options: {})
+
+Write a font to a file.
+
+```ruby
+font = Fontisan::FontLoader.load('input.ttf')
+
+# Write as TTF
+Fontisan::FontWriter.write(font, 'output.ttf')
+
+# Write as OTF
+Fontisan::FontWriter.write(font, 'output.otf')
+
+# Write as WOFF2
+Fontisan::FontWriter.write(font, 'output.woff2')
+
+# With options
+options = Fontisan::ConversionOptions.new(
+  generating: { optimize_tables: true }
+)
+Fontisan::FontWriter.write(font, 'output.ttf', options: options)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| font | SfntFont, Type1Font | Font object |
+| path | String | Output file path |
+| options | ConversionOptions | Optional settings |
+
+**Returns:** Boolean
+
+### write_to_file(data, path, sfnt_version: nil)
+
+Write raw font data to a file.
+
+```ruby
+# Write raw table data
+Fontisan::FontWriter.write_to_file(
+  font.table_data,
+  'output.ttf',
+  sfnt_version: 0x00010000
+)
+```
+
+## Output Formats
+
+| Format | Extension | Notes |
+|--------|-----------|-------|
+| TTF | .ttf | TrueType |
+| OTF | .otf | OpenType/CFF |
+| WOFF | .woff | Web Open Font Format |
+| WOFF2 | .woff2 | Web Open Font Format 2 |
+| PFB | .pfb | Adobe Type 1 |
+| SVG | .svg | SVG Font |
+
+## Examples
+
+### Convert and Write
+
+```ruby
+# Load TTF
+font = Fontisan::FontLoader.load('input.ttf')
+
+# Convert to OTF
+options = Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
+converter = Fontisan::Converters::OutlineConverter.new
+otf_tables = converter.convert(font, options: options)
+
+# Write OTF
+Fontisan::FontWriter.write(otf_tables, 'output.otf')
+```
+
+### Batch Writing
+
+```ruby
+fonts.each_with_index do |font, i|
+  Fontisan::FontWriter.write(font, "output-#{i}.ttf")
+end
+```
+
+### Web Optimization
+
+```ruby
+font = Fontisan::FontLoader.load('input.otf')
+options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+Fontisan::FontWriter.write(font, 'output.woff2', options: options)
+```

data/docs/api/index.md

@@ -0,0 +1,79 @@
+---
+title: API Reference
+---
+
+# API Reference
+
+This section provides detailed API documentation for Fontisan's core classes, converters, validators, and models.
+
+## Core Classes
+
+- [FontLoader](/api/font-loader) — Unified font loading with automatic format detection
+- [FontWriter](/api/font-writer) — Write fonts to various formats
+- [ConversionOptions](/api/conversion-options) — Type-safe conversion configuration
+- [SfntFont](/api/sfnt-font) — Base class for TrueType/OpenType fonts
+- [Type1Font](/api/type1-font) — Adobe Type 1 font handler
+
+## Converters
+
+- [OutlineConverter](/api/converters/outline-converter) — TTF ↔ OTF outline conversion
+- [CurveConverter](/api/converters/curve-converter) — Quadratic ↔ Cubic curve conversion
+- [HintConverter](/api/converters/hint-converter) — TrueType ↔ PostScript hint conversion
+
+## Validators
+
+- [FontValidator](/api/validators/font-validator) — Main validation entry point
+- [ValidationProfile](/api/validators/profile) — Validation profile definitions
+- [ValidationHelper](/api/validators/helper) — Individual validation helpers
+
+## Models
+
+- [Glyph](/api/models/glyph) — Font glyph representation
+- [GlyphAccessor](/api/models/glyph-accessor) — Unified glyph access with caching
+- [TableAnalyzer](/api/models/table-analyzer) — Font table analysis
+
+## Using the API
+
+### Loading Fonts
+
+```ruby
+require 'fontisan'
+
+# Automatic format detection
+font = Fontisan::FontLoader.load('font.ttf')
+font = Fontisan::FontLoader.load('font.otf')
+font = Fontisan::FontLoader.load('font.pfb')
+
+# Load from IO
+font = Fontisan::FontLoader.load(io)
+```
+
+### Converting Fonts
+
+```ruby
+# Get recommended options
+options = Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
+
+# Convert with options
+converter = Fontisan::Converters::OutlineConverter.new
+tables = converter.convert(font, options: options)
+
+# Write the result
+Fontisan::FontWriter.write(font, 'output.otf')
+```
+
+### Validating Fonts
+
+```ruby
+# Validate with a profile
+result = Fontisan::FontValidator.validate('font.ttf', profile: :google_fonts)
+
+# Check results
+if result.passed?
+  puts "Font is valid!"
+else
+  result.errors.each do |error|
+    puts "#{error.code}: #{error.message}"
+  end
+end
+```

data/docs/api/models/glyph-accessor.md

@@ -0,0 +1,43 @@
+---
+title: GlyphAccessor
+---
+
+# GlyphAccessor
+
+Unified glyph access with caching.
+
+## Overview
+
+`Fontisan::GlyphAccessor` provides efficient glyph access.
+
+## Methods
+
+### at(id) / get(id)
+
+Access glyph by ID.
+
+```ruby
+glyph = font.glyphs[42]
+```
+
+### each
+
+Iterate over all glyphs.
+
+```ruby
+font.glyphs.each do |glyph|
+  puts glyph.name
+end
+```
+
+### count
+
+Get glyph count.
+
+```ruby
+count = font.glyphs.count
+```
+
+## See Also
+
+- [Glyph](/api/models/glyph)

data/docs/api/models/glyph.md

@@ -0,0 +1,40 @@
+---
+title: Glyph
+---
+
+# Glyph
+
+Font glyph representation.
+
+## Overview
+
+`Fontisan::Glyph` represents a single glyph.
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | Integer | Glyph ID |
+| `name` | String | Glyph name |
+| `unicode` | Integer | Unicode codepoint |
+| `bounds` | Hash | Bounding box |
+| `contours` | Array | Outline contours |
+
+## Methods
+
+### outline
+
+Get glyph outline.
+
+```ruby
+outline = glyph.outline
+outline.contours.each do |contour|
+  contour.points.each do |point|
+    puts "(#{point.x}, #{point.y})"
+  end
+end
+```
+
+## See Also
+
+- [GlyphAccessor](/api/models/glyph-accessor)

data/docs/api/models/table-analyzer.md

@@ -0,0 +1,35 @@
+---
+title: TableAnalyzer
+---
+
+# TableAnalyzer
+
+Font table analysis.
+
+## Overview
+
+`Fontisan::TableAnalyzer` analyzes font tables.
+
+## Methods
+
+### analyze(fonts, parallel: false)
+
+Analyze fonts for table sharing.
+
+```ruby
+analyzer = Fontisan::TableAnalyzer.new(fonts, parallel: true)
+stats = analyzer.analyze
+puts "Shared tables: #{stats.shared_count}"
+```
+
+### checksum(table)
+
+Calculate table checksum.
+
+```ruby
+checksum = analyzer.checksum(font.tables['head'])
+```
+
+## See Also
+
+- [Collections Guide](/guide/formats/collections)

data/docs/api/sfnt-font.md

@@ -0,0 +1,53 @@
+---
+title: SfntFont
+---
+
+# SfntFont
+
+Base class for TrueType and OpenType fonts.
+
+## Overview
+
+`Fontisan::SfntFont` is the base class for sfnt-based fonts (TTF, OTF, WOFF, WOFF2).
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tables` | Hash | Font tables by tag |
+| `glyphs` | GlyphAccessor | Glyph access object |
+| `family_name` | String | Font family name |
+| `style` | String | Font style |
+| `version` | String | Font version |
+
+## Methods
+
+### table(tag)
+
+Access a specific table.
+
+```ruby
+head = font.table('head')
+name = font.table('name')
+```
+
+### glyph_name(id)
+
+Get glyph name by ID.
+
+```ruby
+name = font.glyph_name(42)
+```
+
+### glyph_count
+
+Get total glyph count.
+
+```ruby
+count = font.glyph_count
+```
+
+## See Also
+
+- [FontLoader](/api/font-loader)
+- [Type1Font](/api/type1-font)

data/docs/api/type1-font.md

@@ -0,0 +1,43 @@
+---
+title: Type1Font
+---
+
+# Type1Font
+
+Adobe Type 1 font handler.
+
+## Overview
+
+`Fontisan::Type1Font` handles Adobe Type 1 fonts (PFB/PFA).
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `font_name` | String | Font name |
+| `family_name` | String | Family name |
+| `charstrings` | Hash | Glyph outlines |
+| `private_dict` | Hash | Private dictionary |
+
+## Methods
+
+### glyph_count
+
+Get total glyph count.
+
+```ruby
+count = font.glyph_count
+```
+
+### charstring(glyph_name)
+
+Get CharString for a glyph.
+
+```ruby
+cs = font.charstring('A')
+```
+
+## See Also
+
+- [FontLoader](/api/font-loader)
+- [SfntFont](/api/sfnt-font)

data/docs/api/validators/font-validator.md

@@ -0,0 +1,31 @@
+---
+title: FontValidator
+---
+
+# FontValidator
+
+Main validation entry point.
+
+## Overview
+
+`Fontisan::Validators::FontValidator` validates fonts against profiles.
+
+## Class Methods
+
+### validate(path, profile: :production)
+
+Validate a font file.
+
+```ruby
+result = Fontisan::Validators::FontValidator.validate('font.ttf', profile: :web)
+if result.valid?
+  puts "Font is valid"
+else
+  puts "Errors: #{result.errors.length}"
+end
+```
+
+## See Also
+
+- [Validation Guide](/guide/validation/)
+- [ValidationProfile](/api/validators/profile)

data/docs/api/validators/helper.md

@@ -0,0 +1,36 @@
+---
+title: ValidationHelper
+---
+
+# ValidationHelper
+
+Individual validation helpers.
+
+## Overview
+
+Validation helpers perform specific checks.
+
+## Categories
+
+| Category | Helpers | Focus |
+|----------|---------|-------|
+| Table | 12 | Table structure |
+| Name | 8 | Name records |
+| Head | 6 | Header validation |
+| Metrics | 10 | Font metrics |
+| Glyph | 8 | Glyph data |
+| CMAP | 6 | Character mapping |
+| Layout | 6 | GSUB/GPOS |
+
+## Using Helpers
+
+```ruby
+validator = Fontisan::Validators::FontValidator.new(font)
+result = validator.check_required_tables
+puts result.valid?
+```
+
+## See Also
+
+- [FontValidator](/api/validators/font-validator)
+- [Validation Helpers Guide](/guide/validation/helpers)

data/docs/api/validators/profile.md

@@ -0,0 +1,39 @@
+---
+title: ValidationProfile
+---
+
+# ValidationProfile
+
+Validation profile definitions.
+
+## Overview
+
+`Fontisan::Validators::ValidationProfile` defines validation profiles.
+
+## Built-in Profiles
+
+| Profile | Checks | Use Case |
+|---------|--------|----------|
+| `indexability` | 8 | Font discovery |
+| `usability` | 26 | Installation |
+| `production` | 37 | Quality assurance |
+| `web` | 18 | Web deployment |
+| `spec_compliance` | Full | Spec audit |
+
+## Methods
+
+### checks
+
+Get list of checks in profile.
+
+```ruby
+profile = Fontisan::Validators::ValidationProfile[:production]
+profile.checks.each do |check|
+  puts check.id
+end
+```
+
+## See Also
+
+- [FontValidator](/api/validators/font-validator)
+- [Validation Helpers](/guide/validation/helpers)

data/docs/cli/convert.md

@@ -0,0 +1,87 @@
+---
+title: convert
+---
+
+# convert
+
+Convert individual fonts between different formats.
+
+::: tip For Collection Formats
+Use [pack/unpack](/cli/pack) to work with TTC, OTC, and dfont collections. The convert command is for individual font files only.
+:::
+
+## Quick Reference
+
+```bash
+fontisan convert <input> --to <format> [options]
+```
+
+## Supported Formats
+
+These are individual font formats that can be converted:
+
+| Format | Read | Write | Description |
+|--------|:----:|:-----:|-------------|
+| TTF | ✅ | ✅ | TrueType (glyf outlines) |
+| OTF | ✅ | ✅ | OpenType (CFF outlines) |
+| WOFF | ✅ | ✅ | Web Open Font Format |
+| WOFF2 | ✅ | ✅ | Web Open Font Format 2 |
+| PFB/PFA | ✅ | — | Adobe Type 1 (read for conversion) |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--to FORMAT` | Target format (ttf, otf, woff, woff2) |
+| `--output FILE` | Output file path |
+| `--optimize` | Enable outline optimization |
+| `--flatten` | Flatten composite glyphs |
+
+## Common Workflows
+
+### Convert for Web
+
+```bash
+# TTF to WOFF2 (recommended for modern browsers)
+fontisan convert font.ttf --to woff2 --output font.woff2
+
+# OTF to WOFF (broader compatibility)
+fontisan convert font.otf --to woff --output font.woff
+```
+
+### Convert Between Outline Formats
+
+```bash
+# TrueType to OpenType (glyf → CFF)
+fontisan convert font.ttf --to otf --output font.otf
+
+# OpenType to TrueType (CFF → glyf)
+fontisan convert font.otf --to ttf --output font.ttf
+```
+
+### Convert Legacy Type 1 Fonts
+
+```bash
+# Type 1 to OpenType
+fontisan convert font.pfb --to otf --output font.otf
+```
+
+## Working with Collections
+
+Collection formats (TTC, OTC, dfont) contain multiple fonts. To convert fonts from a collection:
+
+```bash
+# Step 1: Extract fonts from collection
+fontisan unpack family.ttc --output-dir ./extracted
+
+# Step 2: Convert each font
+fontisan convert ./extracted/Font-Regular.ttf --to woff2 --output Font-Regular.woff2
+fontisan convert ./extracted/Font-Bold.ttf --to woff2 --output Font-Bold.woff2
+
+# Or extract and convert in one step:
+fontisan unpack family.ttc --output-dir ./web --format woff2
+```
+
+## Detailed Documentation
+
+For comprehensive documentation including curve conversion, hint handling, and advanced options, see the [convert command guide](/guide/cli/convert).