fontisan 0.2.13 → 0.2.16

data/docs/guide/cli/validate.md

@@ -0,0 +1,139 @@
+---
+title: validate
+---
+
+# validate
+
+Validate fonts for correctness.
+
+## Usage
+
+```bash
+fontisan validate FONT [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `FONT` | Font file to validate |
+| `FONT ...` | Multiple files |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-t, --profile PROFILE` | Validation profile |
+| `-S, --summary` | Show summary only |
+| `-T, --table` | Table format output |
+| `--list` | List available profiles |
+
+## Profiles
+
+| Profile | Description |
+|---------|-------------|
+| `indexability` | Fast font discovery |
+| `usability` | Installation compatibility |
+| `production` | Comprehensive quality (default) |
+| `web` | Web embedding readiness |
+| `spec_compliance` | Full spec compliance |
+
+## Examples
+
+### Basic Validation
+
+```bash
+fontisan validate font.ttf
+
+# Font: font.ttf
+# Status: VALID
+#
+# Summary:
+#   Checks performed: 37
+#   Passed: 37
+#   Failed: 0
+```
+
+### With Profile
+
+```bash
+fontisan validate font.ttf -t web
+
+# Font: font.ttf
+# Profile: web
+# Status: INVALID
+#
+# Summary:
+#   Checks performed: 18
+#   Passed: 17
+#   Failed: 1
+#
+# Failed checks:
+#   web_font_tables - Missing required GSUB table
+```
+
+### Summary Only
+
+```bash
+fontisan validate font.ttf -S
+
+# font.ttf: VALID (37/37 checks passed)
+```
+
+### Table Format
+
+```bash
+fontisan validate font.ttf -T
+
+# CHECK_ID            | STATUS | SEVERITY | TABLE
+# --------------------------------------------------
+# required_tables     | PASS   | error    | N/A
+# name_version        | PASS   | error    | name
+# family_name         | PASS   | error    | name
+# head_magic          | PASS   | error    | head
+# ...
+```
+
+### Multiple Files
+
+```bash
+fontisan validate fonts/*.ttf
+
+# fonts/regular.ttf: VALID
+# fonts/bold.ttf: VALID
+# fonts/italic.ttf: INVALID (1 error)
+```
+
+### List Profiles
+
+```bash
+fontisan validate --list
+
+# Available validation profiles:
+#   indexability    - Fast validation for font discovery
+#   usability       - Basic usability for installation
+#   production      - Comprehensive quality checks
+#   web             - Web embedding and optimization
+#   spec_compliance - Full OpenType spec compliance
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Valid |
+| 1 | Invalid (errors found) |
+| 2 | Error (file not found, etc.) |
+
+## Use in Scripts
+
+```bash
+# Validate before release
+fontisan validate font.ttf -t production
+if [ $? -eq 0 ]; then
+  echo "Ready for release"
+else
+  echo "Validation failed"
+  exit 1
+fi
+```

data/docs/guide/color-fonts/bitmaps.md

@@ -0,0 +1,177 @@
+---
+title: Bitmap Color Fonts
+---
+
+# Bitmap Color Fonts
+
+Bitmap color fonts store pixel images at specific sizes.
+
+## Formats
+
+| Format | Tables | Platform |
+|--------|--------|----------|
+| sbix | sbix | Apple |
+| CBDT/CBLC | CBDT, CBLC | Google/Android |
+
+## sbix (Apple)
+
+sbix stores bitmap images at multiple resolutions.
+
+### Structure
+
+```ruby
+sbix = font.tables['sbix']
+
+# Strikes (image sets at different sizes)
+sbix.strikes.each do |strike|
+  puts "Strike at #{strike.ppem} ppem"
+
+  strike.glyphs.each do |glyph_id, image|
+    puts "  Glyph #{glyph_id}: #{image.format}"
+  end
+end
+```
+
+### Image Formats
+
+- `png ` — PNG image
+- `jpg ` — JPEG image
+- `tiff` — TIFF image
+- `dupe` — Duplicate of another glyph
+
+### Accessing Images
+
+```ruby
+sbix = font.tables['sbix']
+strike = sbix.strikes.first
+
+glyph_id = 42
+image = strike.image_for(glyph_id)
+
+puts "Format: #{image.format}"
+puts "Data size: #{image.data.length} bytes"
+```
+
+## CBDT/CBLC (Android)
+
+CBDT/CBLC stores bitmap images for Android.
+
+### Structure
+
+```ruby
+cbdt = font.tables['CBDT']
+cblc = font.tables['CBLC']
+
+# CBLC has location data
+cblc.strikes.each do |strike|
+  puts "Strike at #{strike.ppem}x#{strike.ppem}"
+
+  strike.glyph_ranges.each do |range|
+    puts "  Glyphs #{range.start}..#{range.end}"
+  end
+end
+
+# CBDT has actual bitmap data
+```
+
+### Bitmap Formats
+
+- **Small metrics** — For small glyphs
+- **Big metrics** — For larger glyphs
+- **Bit aligned** — 1, 2, 4, or 8 bits per pixel
+
+### Accessing Bitmaps
+
+```ruby
+cbdt = font.tables['CBDT']
+cblc = font.tables['CBLC']
+
+glyph_id = 42
+strike_index = 0
+
+# Get bitmap location
+location = cblc.location(strike_index, glyph_id)
+
+if location
+  # Get bitmap data
+  bitmap = cbdt.bitmap(location)
+  puts "Size: #{bitmap.width}x#{bitmap.height}"
+  puts "Data: #{bitmap.data.length} bytes"
+end
+```
+
+## Working with Bitmaps
+
+### List Available Sizes
+
+```ruby
+sbix = font.tables['sbix']
+
+if sbix
+  puts "Available sizes:"
+  sbix.strikes.each do |strike|
+    puts "  #{strike.ppem} ppem"
+  end
+end
+```
+
+### Export Bitmaps
+
+```ruby
+sbix = font.tables['sbix']
+strike = sbix.strikes.first
+
+sbix.glyphs.each do |glyph_id, image|
+  if image.format == 'png '
+    File.write("glyph-#{glyph_id}.png", image.data)
+  end
+end
+```
+
+## Conversion
+
+### Preserve Bitmaps
+
+```bash
+# Bitmaps preserved during same-format conversion
+fontisan convert bitmap-font.ttf --to ttf --output bitmap-font.ttf
+```
+
+### Remove Bitmaps
+
+```bash
+# Create outline-only version
+fontisan convert bitmap-font.ttf --to ttf --no-bitmaps --output outline-only.ttf
+```
+
+## Comparison
+
+| Feature | sbix | CBDT/CBLC |
+|---------|------|-----------|
+| Platform | Apple | Android |
+| Image formats | PNG, JPEG, TIFF | Raw bitmap |
+| Scalability | No | No |
+| File size | Larger | Smaller |
+| Quality | Photo-realistic | Limited |
+
+## Limitations
+
+### Bitmap Scaling
+
+Bitmap fonts don't scale well:
+- Each strike is designed for a specific ppem
+- Scaling up causes pixelation
+- Scaling down causes aliasing
+
+### Variable Fonts
+
+Bitmap fonts don't work with variation:
+- No interpolation possible
+- Must provide strikes for each instance
+
+## Best Practices
+
+1. **Provide multiple strikes** — Cover common sizes
+2. **Use PNG for sbix** — Best quality/size tradeoff
+3. **Test on target platforms** — Rendering varies
+4. **Consider outline fallback** — For unavailable sizes

data/docs/guide/color-fonts/colr-cpal.md

@@ -0,0 +1,175 @@
+---
+title: COLR/CPAL Color Fonts
+---
+
+# COLR/CPAL Color Fonts
+
+COLR/CPAL is a modern color font format using layered vector glyphs.
+
+## Overview
+
+- **COLR** — Defines glyph layers and their order
+- **CPAL** — Defines color palettes
+
+## Structure
+
+### COLR Table
+
+```ruby
+colr = font.tables['COLR']
+
+# Base glyphs (color emoji)
+base_glyphs = colr.base_glyphs
+
+# Layers for a base glyph
+layers = colr.layers_for(glyph_id)
+# Returns array of { glyph_id:, palette_index: }
+```
+
+### CPAL Table
+
+```ruby
+cpal = font.tables['CPAL']
+
+# Number of palettes
+num_palettes = cpal.num_palettes
+
+# Colors in a palette
+palette_colors = cpal.palette(0)  # First palette
+
+# Get specific color
+color = cpal.color(palette_index)
+# Returns { r:, g:, b:, a: }
+```
+
+## Working with COLR/CPAL
+
+### List Color Glyphs
+
+```ruby
+font = Fontisan::FontLoader.load('color-font.ttf')
+colr = font.tables['COLR']
+
+colr.base_glyphs.each do |glyph_id|
+  glyph_name = font.glyph_name(glyph_id)
+  puts "#{glyph_name} (#{glyph_id})"
+end
+```
+
+### Get Layer Colors
+
+```ruby
+colr = font.tables['COLR']
+cpal = font.tables['CPAL']
+
+colr.base_glyphs.each do |glyph_id|
+  puts "Glyph #{glyph_id}:"
+
+  colr.layers_for(glyph_id).each do |layer|
+    color = cpal.color(layer[:palette_index])
+    layer_name = font.glyph_name(layer[:glyph_id])
+    puts "  #{layer_name}: rgba(#{color[:r]}, #{color[:g]}, #{color[:b]}, #{color[:a]})"
+  end
+end
+```
+
+## Color Palettes
+
+### Default Palette
+
+```ruby
+cpal = font.tables['CPAL']
+
+# First palette (default)
+default_palette = cpal.palette(0)
+puts "Default palette has #{default_palette.length} colors"
+```
+
+### Multiple Palettes
+
+Some fonts have alternative color schemes:
+
+```ruby
+cpal = font.tables['CPAL']
+
+(0...cpal.num_palettes).each do |palette_index|
+  puts "Palette #{palette_index}:"
+  cpal.palette(palette_index).each_with_index do |color, i|
+    puts "  Color #{i}: rgba(#{color[:r]}, #{color[:g]}, #{color[:b]}, #{color[:a]})"
+  end
+end
+```
+
+## Conversion
+
+### Preserve COLR/CPAL
+
+```bash
+# COLR/CPAL is preserved during same-format conversion
+fontisan convert color-font.ttf --to otf --output color-font.otf
+```
+
+### Flatten to PNG
+
+```bash
+# Export color glyphs as PNG images
+fontisan export color-font.ttf --format png --output ./images/
+```
+
+## Creating COLR/CPAL
+
+Currently Fontisan focuses on reading and preserving COLR/CPAL. For creation, consider:
+
+1. Design glyphs in layers
+2. Assign palette indices
+3. Define color palettes
+4. Use font editor (Glyphs, FontForge)
+
+## Browser Support
+
+| Browser | Version |
+|---------|---------|
+| Chrome | 98+ |
+| Firefox | 105+ |
+| Safari | 15.4+ |
+| Edge | 98+ |
+
+## Validation
+
+```bash
+# Validate color font
+fontisan validate color-font.ttf
+
+# Check COLR structure
+fontisan info color-font.ttf
+```
+
+## Example
+
+### Analyze Color Emoji Font
+
+```ruby
+font = Fontisan::FontLoader.load('emoji.ttf')
+colr = font.tables['COLR']
+cpal = font.tables['CPAL']
+
+puts "Color glyphs: #{colr.base_glyphs.length}"
+puts "Palettes: #{cpal.num_palettes}"
+
+# Find glyph for specific character
+cmap = font.tables['cmap']
+glyph_id = cmap.glyph_id_for('😀')
+
+if colr.base_glyphs.include?(glyph_id)
+  puts "😀 is a color glyph"
+
+  layers = colr.layers_for(glyph_id)
+  puts "Composed of #{layers.length} layers:"
+
+  layers.each do |layer|
+    layer_name = font.glyph_name(layer[:glyph_id])
+    color = cpal.color(layer[:palette_index])
+    puts "  #{layer_name}: rgba(#{color[:r]}, #{color[:g]}, #{color[:b]})"
+  end
+end
+```

data/docs/guide/color-fonts/index.md

@@ -0,0 +1,140 @@
+---
+title: Color Fonts Overview
+---
+
+# Color Fonts Overview
+
+Fontisan supports multiple color font formats for modern typography.
+
+## Supported Formats
+
+| Format | Tables | Description |
+|--------|--------|-------------|
+| COLR/CPAL | COLR, CPAL | Layered vector glyphs |
+| sbix | sbix | Bitmap images (Apple) |
+| CBDT/CBLC | CBDT, CBLC | Bitmap images (Google) |
+| SVG | SVG | SVG embedded in font |
+
+## COLR/CPAL
+
+COLR/CPAL uses layered vector glyphs with palette-based coloring.
+
+### Advantages
+
+- **Scalable** — Vectors scale to any size
+- **Small file size** — Efficient compression
+- **Variable support** — Works with variable fonts
+- **Wide support** — Modern browsers and apps
+
+### Structure
+
+```
+COLR table:
+- Glyph layers (which glyphs make up each color glyph)
+- Layer order (back to front)
+
+CPAL table:
+- Color palettes (sets of colors)
+- Color values (RGBA for each palette entry)
+```
+
+## sbix
+
+sbix stores bitmap images at multiple resolutions (Apple format).
+
+### Advantages
+
+- **Photo-realistic** — Any image quality
+- **Multiple sizes** — Different bitmaps for different sizes
+
+### Structure
+
+```
+sbix table:
+- Strikes (image sets at different sizes)
+- Per-glyph images (PNG, JPG, etc.)
+```
+
+## CBDT/CBLC
+
+CBDT/CBLC stores bitmap images (Google/Android format).
+
+### Advantages
+
+- **Android support** — Primary Android bitmap format
+- **Multiple sizes** — Different bitmaps per ppem
+
+### Structure
+
+```
+CBLC table:
+- Location data (where each bitmap is)
+- Size information
+
+CBDT table:
+- Bitmap data (actual images)
+```
+
+## SVG Color Fonts
+
+SVG fonts embed complete SVG documents.
+
+### Advantages
+
+- **Full SVG features** — Gradients, effects, etc.
+- **Standalone** — No external resources
+
+### Limitations
+
+- **Large file size** — XML overhead
+- **Limited support** — Not all browsers
+
+## Guides
+
+- [COLR/CPAL](/guide/color-fonts/colr-cpal) — Vector layered color fonts
+- [Bitmaps](/guide/color-fonts/bitmaps) — sbix and CBDT/CBLC
+- [SVG Color](/guide/color-fonts/svg) — SVG-based color fonts
+
+## Quick Start
+
+### Check for Color Tables
+
+```ruby
+font = Fontisan::FontLoader.load('font.ttf')
+
+if font.tables['COLR']
+  puts "COLR/CPAL color font"
+end
+
+if font.tables['sbix']
+  puts "sbix bitmap font"
+end
+
+if font.tables['CBDT']
+  puts "CBDT/CBLC bitmap font"
+end
+
+if font.tables['SVG']
+  puts "SVG color font"
+end
+```
+
+### Get Color Information
+
+```ruby
+colr = font.tables['COLR']
+cpal = font.tables['CPAL']
+
+if colr && cpal
+  # Get base glyphs (color emoji)
+  colr.base_glyphs.each do |glyph_id|
+    puts "Base glyph: #{glyph_id}"
+    puts "  Layers: #{colr.layers_for(glyph_id).length}"
+
+    colr.layers_for(glyph_id).each do |layer|
+      color = cpal.color(layer[:palette_index])
+      puts "    Layer #{layer[:glyph_id]}: #{color}"
+    end
+  end
+end
+```