fontisan 0.2.0 → 0.2.2

data/README.adoc

@@ -56,6 +56,7 @@ gem install fontisan
 
 == Features
 
+* Bidirectional font hint conversion (see link:docs/FONT_HINTING.adoc[Font Hinting Guide])
 * Extract comprehensive font metadata (name, version, designer, license, etc.)
 * List OpenType tables with checksums and offsets
 * Extract glyph names from post table
@@ -71,7 +72,7 @@ gem install fontisan
 * Collection management (pack/unpack TTC/OTC files with table deduplication)
 * Support for TTF, OTF, TTC, OTC font formats (production ready)
 * WOFF format support (reading complete, writing functional, pending full integration)
-* WOFF2 format support (reading partial, writing planned)
+* WOFF2 format support (reading complete with table transformations, writing planned)
 * SVG font generation (complete)
 * TTX/YAML/JSON export (complete)
 * Command-line interface with 18 commands
@@ -85,1873 +86,2074 @@ gem install fontisan
 * 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)
 
-NOTE: TTF ↔ OTF outline format conversion is in active development (Phase 1, ~80% complete). The universal outline model, CFF builders, curve converter, and compound glyph support are fully functional. Simple and compound glyphs convert successfully. See link:docs/IMPLEMENTATION_STATUS_V4.md[Implementation Status] for detailed progress tracking.
 
-
-== Loading Modes
+== Font information
 
 === General
 
-Fontisan provides a flexible loading modes architecture that enables efficient
-font parsing for different use cases.
+Extract comprehensive metadata from font files. This includes font names,
+version information, designer credits, vendor details, licensing information,
+and font metrics.
 
-The system supports two distinct modes:
+[source,shell]
+----
+$ fontisan info FONT_FILE [--format FORMAT] [--brief]
+----
 
-`:full` mode:: (default) Loads all tables in the font for complete analysis and
-manipulation
+Where,
 
-`:metadata` mode:: Loads only metadata tables needed for font identification and
-metrics (similar to `otfinfo` functionality). This mode is around 5x faster
-than full parsing and uses significantly less memory.
+`FONT_FILE`:: Path to the font file (OTF, TTF, TTC, OTF)
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+`--brief`:: Show only basic font information
 
-This architecture is particularly useful for software that only
-needs basic font information without full parsing overhead, such as
-font indexing systems or font discovery tools.
 
-This mode was developed to improve performance in font indexing in the
-https://github.com/fontist/fontist[Fontist] library, where system fonts
-need to be scanned quickly without loading unnecessary data.
+=== Brief mode
 
-A font file opened in `:metadata` mode will only have a subset of tables
-loaded, and attempts to access non-loaded tables will return `nil`.
+==== General
 
-[source,ruby]
-----
-font = Fontisan::FontLoader.load('font.ttf', mode: :metadata)
+For font indexing systems that need to scan thousands of fonts quickly, use the
+`--brief` flag to get essential metadata only. This mode uses metadata loading
+and is **5x faster** than full mode.
 
-# Check table availability before accessing
-font.table_available?("name")  # => true
-font.table_available?("GSUB")  # => false
+Brief mode provides significant performance improvements for font indexing:
 
-# Access allowed tables
-font.table("name")  # => Works
-font.table("head")  # => Works
+* **5x faster** than full mode by using the `metadata` load mode
+* **Loads only 6 tables** instead of 15-20 (name, head, hhea, maxp, OS/2, post)
+* **Lower memory usage** through reduced table loading
+* **Optimized for batch processing** of many fonts
 
-# Restricted tables return nil
-font.table("GSUB")  # => nil (not loaded in metadata mode)
-----
+Brief mode populates only the following 13 essential attributes:
 
-You can also set loading modes via the environment:
+Font identification::
+* `font_format` - Font format (truetype, cff)
+* `is_variable` - Whether font is variable
 
-[source,ruby]
-----
-# Set defaults via environment
-ENV['FONTISAN_MODE'] = 'metadata'
-ENV['FONTISAN_LAZY'] = 'false'
+Essential names::
+* `family_name` - Font family name
+* `subfamily_name` - Font subfamily/style
+* `full_name` - Full font name
+* `postscript_name` - PostScript name
 
-# Uses environment settings
-font = Fontisan::FontLoader.load('font.ttf')
+Version info::
+* `version` - Version string
 
-# Explicit parameters override environment
-font = Fontisan::FontLoader.load('font.ttf', mode: :full)
-----
+Metrics::
+* `font_revision` - Font revision number
+* `units_per_em` - Units per em
 
-The loading mode can be queried at any time.
+Vendor::
+* `vendor_id` - Vendor/foundry ID
 
-[source,ruby]
-----
-# Mode stored as font property
-font.loading_mode  # => :metadata or :full
 
-# Table availability checked before access
-font.table_available?(tag)  # => boolean
+==== Command-line usage
 
-# Access restricted based on mode
-font.table(tag)  # => Returns table or raises error
+Syntax:
+
+[source,shell]
+----
+$ fontisan info FONT_FILE --brief [--format FORMAT]
+----
+
+[source,shell]
 ----
+# Individual font
+$ fontisan info font.ttf --brief
+Font type:                TrueType (Not Variable)
+Family:                   Noto Sans
+...
 
+# Collection
+$ fontisan info fonts.ttc --brief
+Collection: fonts.ttc
+Fonts: 35
 
+Font 0 (offset: 152):
+Font type:                OpenType (CFF) (Not Variable)
+Family:                   Noto Serif CJK JP ExtraLight
+...
+----
 
-=== Metadata mode
 
-Loads only 6 tables (name, head, hhea, maxp, OS/2, post) instead of 15-20 tables.
+.Brief mode with default text output
+[example]
+====
+[source,shell]
+----
+$ fontisan info spec/fixtures/fonts/MonaSans/mona-sans-2.0.8/googlefonts/variable/MonaSans[wdth,wght].ttf --brief
 
-.Metadata mode: Fast loading for font identification
-[source,ruby]
+Font type:                TrueType (Variable)
+Family:                   Mona Sans ExtraLight
+Subfamily:                Regular
+Full name:                Mona Sans ExtraLight
+PostScript name:          MonaSans-ExtraLight
+Version:                  Version 2.001
+Vendor ID:                GTHB
+Font revision:            2.00101
+Units per em:             1000
 ----
-font = Fontisan::FontLoader.load('font.ttf', mode: :metadata)
-puts font.family_name          # => "Arial"
-puts font.subfamily_name       # => "Regular"
-puts font.post_script_name     # => "ArialMT"
+====
+
+.Brief mode with JSON output
+[example]
+====
+[source,shell]
+----
+$ fontisan info font.ttf --brief --format json
 ----
 
-Tables loaded:
+[source,json]
+----
+{
+  "font_format": "truetype",
+  "is_variable": false,
+  "family_name": "Open Sans",
+  "subfamily_name": "Regular",
+  "full_name": "Open Sans Regular",
+  "postscript_name": "OpenSans-Regular",
+  "version": "Version 3.000",
+  "font_revision": 3.0,
+  "vendor_id": "2001",
+  "units_per_em": 2048
+}
+----
+====
 
-name:: Font names and metadata
-head:: Font header with global metrics
-hhea:: Horizontal header with line spacing
-maxp:: Maximum profile with glyph count
-OS/2:: OS/2 and Windows metrics
-post:: PostScript information
 
+==== Ruby API usage
 
-In metadata mode, these convenience methods provide direct access to name table
-fields:
+.Basic brief info access
+[example]
+====
+[source,ruby]
+----
+require 'fontisan'
 
-`family_name`:: Font family name (nameID 1)
-`subfamily_name`:: Font subfamily/style name (nameID 2)
-`full_name`:: Full font name (nameID 4)
-`post_script_name`:: PostScript name (nameID 6)
-`preferred_family_name`:: Preferred family name (nameID 16, may be nil)
-`preferred_subfamily_name`:: Preferred subfamily name (nameID 17, may be nil)
-`units_per_em`:: Units per em from head table
+info = Fontisan.info("font.ttf", brief: true)
 
+# Access populated fields
+puts info.family_name       # "Open Sans"
+puts info.postscript_name   # "OpenSans-Regular"
+puts info.is_variable       # false
 
-=== Full mode
+# Non-essential fields are nil
+puts info.copyright         # nil (not populated)
+puts info.designer          # nil (not populated)
 
-Loads all tables in the font for complete analysis and manipulation.
+# Serialize to YAML/JSON
+puts info.to_yaml
+puts info.to_json
+----
+====
 
-.Full mode: Complete font analysis
+.Brief info for font collections
+[example]
+====
 [source,ruby]
 ----
-font = Fontisan::FontLoader.load('font.ttf', mode: :full)
-font.table("GSUB")  # => Available
-font.table("GPOS")  # => Available
+require 'fontisan'
 
-# Check which mode is active
-puts font.loading_mode  # => :metadata or :full
+# Specify font index for TTC/OTC files
+info = Fontisan.info("/path/to/fonts.ttc", brief: true, font_index: 0)
+puts info.family_name
 ----
+====
 
-Tables loaded:
+=== Full mode
 
-* All tables in the font
-* Including GSUB, GPOS, cmap, glyf/CFF, etc.
+==== General
 
-=== Lazy loading option
+In full mode, these additional attributes are populated (remain `nil` in brief
+mode):
 
-Fontisan supports lazy loading of tables in both `:metadata` and `:full` modes.
-When lazy loading is enabled (optional), tables are only parsed when accessed.
+* `postscript_cid_name`, `preferred_family`, `preferred_subfamily`, `mac_font_menu_name`
+* `unique_id`, `description`, `designer`, `designer_url`
+* `manufacturer`, `vendor_url`, `trademark`, `copyright`
+* `license_description`, `license_url`, `sample_text`, `permissions`
 
-Options:
+==== Command-line usage
 
-`false`:: (default) Eager loading. All tables for the selected mode are parsed
-upfront.
+Syntax:
 
-`true`:: Lazy loading enabled. Tables are parsed on-demand.
+[source,shell]
+----
+$ fontisan info FONT_FILE [--format FORMAT]
+----
 
-[source,ruby]
+.Font information for Libertinus Serif Regular
+[example]
+====
+[source,shell]
 ----
-# Metadata mode with lazy loading (default, fastest)
-font = Fontisan::FontLoader.load('font.ttf', mode: :metadata, lazy: true)
+$ fontisan info spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
 
-# Metadata mode with eager loading (loads all metadata tables upfront)
-font = Fontisan::FontLoader.load('font.ttf', mode: :metadata, lazy: false)
+Font type:                TrueType
+Family:                   Libertinus Serif
+Subfamily:                Regular
+Full name:                Libertinus Serif Regular
+PostScript name:          LibertinusSerif-Regular
+Version:                  Version 7.051;RELEASE
+Unique ID:                5.000;QUE ;LibertinusSerif-Regular
+Designer:                 Philipp H. Poll, Khaled Hosny
+Manufacturer:             Caleb Maclennan
+Vendor URL:               https://github.com/alerque/libertinus
+Vendor ID:                QUE
+License Description:      This Font Software is licensed under the SIL Open Font
+                          License, Version 1.1. This license is available with a
+                          FAQ at: https://openfontlicense.org
+License URL:              https://openfontlicense.org
+Font revision:            7.05099
+Permissions:              Installable
+Units per em:             1000
+----
+====
 
-# Full mode with lazy loading (tables loaded on-demand)
-font = Fontisan::FontLoader.load('font.ttf', mode: :full, lazy: true)
 
-# Full mode with eager loading (all tables loaded upfront)
-font = Fontisan::FontLoader.load('font.ttf', mode: :full, lazy: false)
+.Output in structured YAML format
+[example]
+====
+[source,shell]
+----
+$ fontisan info spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --format yaml
 ----
 
+[source,yaml]
+----
+font_format: truetype
+is_variable: false
+family_name: Libertinus Serif
+subfamily_name: Regular
+full_name: Libertinus Serif Regular
+postscript_name: LibertinusSerif-Regular
+version: Version 7.051;RELEASE
+unique_id: 5.000;QUE ;LibertinusSerif-Regular
+designer: Philipp H. Poll, Khaled Hosny
+manufacturer: Caleb Maclennan
+vendor_url: https://github.com/alerque/libertinus
+vendor_id: QUE
+license_description: 'This Font Software is licensed under the SIL Open Font License,
+  Version 1.1. This license is available with a FAQ at: https://openfontlicense.org'
+license_url: https://openfontlicense.org
+font_revision: 7.050994873046875
+permissions: Installable
+units_per_em: 1000
+----
+====
 
 
 
-== Outline Format Conversion
 
-Fontisan supports bidirectional conversion between TrueType (TTF) and OpenType/CFF (OTF) outline formats through a universal outline model.
+== List OpenType tables
 
 === General
 
-The outline converter enables transformation between glyph outline formats:
-
-* **TrueType (TTF)**: Uses quadratic Bézier curves stored in glyf/loc tables
-* **OpenType/CFF (OTF)**: Uses cubic Bézier curves stored in CFF table
+To understanding font structure and verifying table integrity, Fontisan provides
+detailed table listings.
 
-Conversion uses a format-agnostic universal outline model as an intermediate representation, ensuring high-quality results while preserving glyph metrics and bounding boxes.
+Display the font's table directory, showing all OpenType tables with their
+sizes, offsets, and checksums.
 
-=== Using the CLI
+=== Command-line usage
 
-==== Convert TTF to OTF
+Syntax:
 
-[source,bash]
+[source,shell]
 ----
-# Convert TrueType font to OpenType/CFF
-fontisan convert input.ttf --to otf --output output.otf
+$ fontisan tables FONT_FILE [--format FORMAT]
 ----
 
-==== Convert OTF to TTF
+Where,
 
-[source,bash]
+`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+
+.List of OpenType tables in Libertinus Serif Regular
+[example]
+====
+[source,shell]
 ----
-# Convert OpenType/CFF font to TrueType
-fontisan convert input.otf --to ttf --output output.ttf
+$ fontisan tables spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
 ----
 
-==== Format aliases
-
-The converter accepts multiple format aliases:
+[source,text]
+----
+SFNT Version: TrueType (0x00010000)
+Number of tables: 16
 
-[source,bash]
+Tables:
+  GDEF         834 bytes  (offset: 542156, checksum: 0x429C5C0C)
+  GPOS       17870 bytes  (offset: 542992, checksum: 0x29CE4200)
+  OS/2          96 bytes  (offset: 392, checksum: 0x4830F1C3)
+  cmap        3620 bytes  (offset: 11412, checksum: 0x03AD3899)
+  cvt          248 bytes  (offset: 18868, checksum: 0x3098127E)
+  fpgm        3596 bytes  (offset: 15032, checksum: 0x622F0781)
+  gasp           8 bytes  (offset: 542148, checksum: 0x00000010)
+  glyf      484900 bytes  (offset: 30044, checksum: 0x0FF34594)
+  head          54 bytes  (offset: 268, checksum: 0x18F5BDD0)
+  hhea          36 bytes  (offset: 324, checksum: 0x191E2264)
+  hmtx       10924 bytes  (offset: 488, checksum: 0x1F9D892B)
+  loca       10928 bytes  (offset: 19116, checksum: 0x230B1A58)
+  maxp          32 bytes  (offset: 360, checksum: 0x0EF919E7)
+  name         894 bytes  (offset: 514944, checksum: 0x4E9173E6)
+  post       26308 bytes  (offset: 515840, checksum: 0xE3D70231)
+  prep         239 bytes  (offset: 18628, checksum: 0x8B4AB356)
 ----
-# These are equivalent (TrueType)
-fontisan convert font.otf --to ttf --output font.ttf
-fontisan convert font.otf --to truetype --output font.ttf
+====
 
-# These are equivalent (OpenType/CFF)
-fontisan convert font.ttf --to otf --output font.otf
-fontisan convert font.ttf --to opentype --output font.otf
-fontisan convert font.ttf --to cff --output font.otf
+.Output in structured YAML format
+[example]
+====
+[source,shell]
+----
+$ fontisan tables spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --format yaml
 ----
 
-==== Validation
-
-After conversion, validate the output font:
-
-[source,bash]
+[source,yaml]
 ----
-fontisan validate output.otf
-fontisan info output.otf
-fontisan tables output.otf
+---
+sfnt_version: TrueType (0x00010000)
+num_tables: 16
+tables:
+- tag: GDEF
+  length: 834
+  offset: 542156
+  checksum: 1117543436
+- tag: GPOS
+  length: 17870
+  offset: 542992
+  checksum: 701383168
 ----
+====
 
-=== Using the Ruby API
-
-==== Basic conversion
 
-[source,ruby]
-----
-require 'fontisan'
+== List glyph names
 
-# Load a TrueType font
-font = Fontisan::FontLoader.load('input.ttf')
+=== General
 
-# Convert to OpenType/CFF
-converter = Fontisan::Converters::OutlineConverter.new
-tables = converter.convert(font, target_format: :otf)
+Show all glyph names defined in the font's post table. Each glyph is listed with
+its index and name, useful for understanding the font's character coverage.
 
-# Write output
-Fontisan::FontWriter.write_to_file(
-  tables,
-  'output.otf',
-  sfnt_version: 0x4F54544F  # 'OTTO' for OpenType/CFF
-)
-----
+=== Command-line usage
 
-==== Using FormatConverter
+Syntax:
 
-[source,ruby]
+[source,shell]
+----
+$ fontisan glyphs FONT_FILE [--format FORMAT]
 ----
-require 'fontisan'
 
-# Load font
-font = Fontisan::FontLoader.load('input.ttf')
+Where,
 
-# Convert using high-level API
-converter = Fontisan::Converters::FormatConverter.new
-if converter.supported?(:ttf, :otf)
-  tables = converter.convert(font, :otf)
+`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
 
-  # Write output
-  Fontisan::FontWriter.write_to_file(
-    tables,
-    'output.otf',
-    sfnt_version: 0x4F54544F
-  )
-end
+
+.List of glyph names in Libertinus Serif Regular
+[example]
+====
+[source,shell]
+----
+$ fontisan glyphs spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
 ----
 
-==== Check supported conversions
+[source,text]
+----
+Glyph count: 2731
+Source: post_2.0
 
-[source,ruby]
+Glyph names:
+      0  .notdef
+      1  space
+      2  exclam
+      3  quotedbl
+      4  numbersign
+      5  dollar
+      6  percent
+      7  ampersand
+      8  quotesingle
+      9  parenleft
+     10  parenright
+     11  asterisk
+     12  plus
+     13  comma
+     14  hyphen
+     15  period
+     16  slash
+     17  zero
+     18  one
+     19  two
+     20  three
+     ...
 ----
-converter = Fontisan::Converters::FormatConverter.new
+====
 
-# Check if conversion is supported
-converter.supported?(:ttf, :otf)  # => true
-converter.supported?(:otf, :ttf)  # => true
 
-# Get all supported conversions
-converter.all_conversions
-# => [{from: :ttf, to: :otf}, {from: :otf, to: :ttf}, ...]
+== Show Unicode mappings
 
-# Get supported targets for a source format
-converter.supported_targets(:ttf)
-# => [:ttf, :otf, :woff2, :svg]
-----
+=== General
 
-=== Technical Details
+Display Unicode codepoint to glyph index mappings from the cmap table. Shows
+which glyphs are assigned to which Unicode characters.
 
-The converter uses a three-stage pipeline:
+=== Command-line usage
+Syntax:
 
-[source]
+[source,shell]
 ----
-Source Format         Universal Outline         Target Format
--------------         ------------------        -------------
-TrueType (glyf)  →→→  Command-based model  →→→  OpenType/CFF
-Quadratic curves      Path representation        Cubic curves
-On/off-curve pts      (format-agnostic)         CharStrings
-Delta encoding        Bounding boxes             Type 2 operators
-                      Metrics                    Compact encoding
+$ fontisan unicode FONT_FILE [--format FORMAT]
 ----
 
-==== TTF → OTF conversion
-
-. Extract glyphs from glyf/loca tables
-. Convert quadratic Bézier curves to universal outline format
-. Build CFF table with CharStrings INDEX
-. Update maxp table to version 0.5 (CFF format)
-. Update head table (clear indexToLocFormat)
-. Remove glyf/loca tables
-. Preserve all other tables
-
-==== OTF → TTF conversion
-
-. Extract CharStrings from CFF table
-. Convert cubic Bézier curves to universal outline format
-. Convert cubic curves to quadratic using adaptive subdivision
-. Build glyf and loca tables with optimal format selection
-. Update maxp table to version 1.0 (TrueType format)
-. Update head table (set indexToLocFormat)
-. Remove CFF table
-. Preserve all other tables
+Where,
 
-==== Curve conversion
+`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
 
-**Quadratic to cubic** (lossless):
 
-[source]
+.Unicode to glyph mappings in Libertinus Serif Regular
+[example]
+====
+[source,shell]
 ----
-Given quadratic curve with control point Q:
-  P0 (start), Q (control), P2 (end)
-
-Calculate cubic control points:
-  CP1 = P0 + (2/3) × (Q - P0)
-  CP2 = P2 + (2/3) × (Q - P2)
-
-Result: Exact mathematical equivalent
+$ fontisan unicode spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
 ----
 
-**Cubic to quadratic** (adaptive):
-
-[source]
+[source,text]
 ----
-Given cubic curve with control points:
-  P0 (start), CP1, CP2, P3 (end)
-
-Use adaptive subdivision algorithm:
-  1. Estimate error of quadratic approximation
-  2. If error > threshold (0.5 units):
-     - Subdivide cubic curve at midpoint
-     - Recursively convert each half
-  3. Otherwise: Output quadratic approximation
+Unicode mappings: 2382
 
-Result: High-quality approximation with < 0.5 unit deviation
+U+0020  glyph 1  space
+U+0021  glyph 2  exclam
+U+0022  glyph 3  quotedbl
+U+0023  glyph 4  numbersign
+U+0024  glyph 5  dollar
+U+0025  glyph 6  percent
+U+0026  glyph 7  ampersand
+U+0027  glyph 8  quotesingle
+U+0028  glyph 9  parenleft
+U+0029  glyph 10  parenright
+U+002A  glyph 11  asterisk
+U+002B  glyph 12  plus
+U+002C  glyph 13  comma
+U+002D  glyph 14  hyphen
+U+002E  glyph 15  period
+U+002F  glyph 16  slash
+U+0030  glyph 17  zero
+U+0031  glyph 18  one
+...
 ----
+====
 
-=== Compound Glyph Support
 
-Fontisan fully supports compound (composite) glyphs in both conversion directions:
+== Variable font information
 
-* **TTF → OTF**: Compound glyphs are decomposed into simple outlines with transformations applied
-* **OTF → TTF**: CFF glyphs are converted to simple TrueType glyphs
+=== General
 
-==== Decomposition Process
+Display variation axes and named instances for variable fonts. Shows the design
+space and predefined styles available in the font.
 
-When converting TTF to OTF, compound glyphs undergo the following process:
+=== Command-line usage
 
-. Detected from glyf table flags (numberOfContours = -1)
-. Components recursively resolved (handling nested compound glyphs)
-. Transformation matrices applied to each component (translation, scale, rotation)
-. All components merged into a single simple outline
-. Converted to CFF CharString format
+Syntax:
 
-This ensures that all glyphs render identically while maintaining proper metrics and bounding boxes.
+[source,shell]
+----
+$ fontisan variable FONT_FILE [--format FORMAT]
+----
 
-==== Technical Implementation
+Where,
 
-Compound glyphs reference other glyphs by index and apply 2×3 affine transformation matrices:
+`FONT_FILE`:: Path to the variable font file
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
 
-[source]
+
+.Variable font axes and instances in Mona Sans
+[example]
+====
+[source,shell]
+----
+$ fontisan variable spec/fixtures/fonts/MonaSans/variable/MonaSans[wdth,wght].ttf
 ----
-x' = a*x + c*y + e
-y' = b*x + d*y + f
 
-Where:
-- a, d: Scale factors for x and y axes
-- b, c: Rotation/skew components
-- e, f: Translation offsets (x, y position)
+[source,text]
+----
+Axis 0:                 wdth
+Axis 0 name:            Width
+Axis 0 range:           75 125
+Axis 0 default:         100
+Axis 1:                 wght
+Axis 1 name:            Weight
+Axis 1 range:           200 900
+Axis 1 default:         400
+Instance 0 name:        Mona Sans Narrow Thin
+Instance 0 position:    75 200
+Instance 1 name:        Mona Sans Narrow ExtraLight
+Instance 1 position:    75 250
+Instance 2 name:        Mona Sans Narrow Light
+Instance 2 position:    75 300
+...
 ----
+====
 
-The resolver handles:
 
-* Simple glyphs referenced by compounds
-* Nested compound glyphs (compounds referencing other compounds)
-* Circular reference detection with maximum recursion depth (32 levels)
-* Complex transformation matrices (uniform scale, x/y scale, full 2×2 matrix)
+== Generate static instances from variable fonts
 
-=== Subroutine Optimization
+=== General
 
-==== General
+Generate static font instances from variable fonts at specific variation
+coordinates and output in any supported format (TTF, OTF, WOFF).
 
-When converting TrueType (TTF) to OpenType/CFF (OTF), Fontisan can automatically generate CFF subroutines to reduce file size. Subroutines extract repeated CharString patterns across glyphs and store them once, significantly reducing CFF table size while maintaining identical glyph rendering.
+=== Command-line usage
 
-Key features:
+Syntax:
 
-* **Pattern Analysis**: Analyzes byte sequences across all CharStrings to identify repeating patterns
-* **Frequency-Based Selection**: Prioritizes patterns that provide maximum space savings
-* **Configurable Thresholds**: Customizable minimum pattern length and maximum subroutine count
-* **Ordering Optimization**: Automatically orders subroutines by frequency for better compression
-
-Typical space savings: 30-50% reduction in CFF table size for fonts with similar glyph shapes.
-
-NOTE: Current implementation calculates accurate optimization metrics but does not modify the output CFF table. Full CFF serialization with subroutines will be available in the next development phase.
-
-==== Subroutine Optimization Improvements (v2.0.0-rc1)
-
-===== Bug Fixes
-
-Three critical bugs were fixed in v2.0.0-rc1 to improve CharString parsing and round-trip validation:
-
-. **CFF Bias Calculation**: Fixed incorrect bias values that caused wrong subroutine calls
-  * Changed from `bias=0` to `bias=107` for <1240 subroutines (per CFF specification)
-  * Changed from `bias=107` to `bias=1131` for 1240-33899 subroutines
-  * Encoder and decoder now use matching bias values
-  * Eliminates "nil can't be coerced into Float" errors
-
-. **Operator Boundaries**: Patterns now respect CharString structure to prevent malformed sequences
-  * Added [`find_operator_boundaries`](lib/fontisan/optimizers/pattern_analyzer.rb) method
-  * Added [`skip_number`](lib/fontisan/optimizers/pattern_analyzer.rb) helper for multi-byte parsing
-  * Prevents splitting multi-byte number encodings (1-5 bytes)
-  * Prevents separating operators from their operands
-
-. **Overlap Prevention**: Multiple patterns at same positions no longer cause byte corruption
-  * Added [`remove_overlaps`](lib/fontisan/optimizers/charstring_rewriter.rb) method
-  * Keeps patterns with higher savings when overlaps detected
-  * Ensures data integrity during CharString rewriting
-
-These fixes significantly reduce parsing errors after optimization (from 91 failures to ~140 warnings in integration tests).
-
-===== Edge Cases
-
-The optimizer now correctly handles:
-
-* **Multi-byte numbers**: Number encodings from 1-5 bytes (CFF Type 2 format)
-* **Two-byte operators**: Operators with 0x0c prefix (e.g., [`div`](lib/fontisan/tables/cff/charstring.rb), [`flex`](lib/fontisan/tables/cff/charstring.rb))
-* **Overlapping patterns**: Multiple patterns at same byte positions
-* **Stack-neutral validation**: Patterns verified to maintain consistent stack state
-
-===== Troubleshooting
+[source,shell]
+----
+$ fontisan instance VARIABLE_FONT [OPTIONS]
+----
 
-If you encounter CharString parsing errors after optimization:
+Where,
 
-. **Verify bias calculation**: Ensure bias matches CFF specification (107, 1131, or 32768)
-. **Check operator boundaries**: Patterns should only be extracted at valid boundaries
-. **Ensure no overlaps**: Multiple patterns should not occupy same byte positions
-. **Enable verbose mode**: Use `--verbose` flag for detailed diagnostics
+`VARIABLE_FONT`:: Path to the variable font file
+`OPTIONS`:: Instance generation options
 
-Example debugging workflow:
+Options:
 
-[source,bash]
+`--wght VALUE`:: Weight axis value
+`--wdth VALUE`:: Width axis value
+`--slnt VALUE`:: Slant axis value
+`--ital VALUE`:: Italic axis value
+`--opsz VALUE`:: Optical size axis value
+`--to FORMAT`:: Output format: `ttf` (default), `otf`, `woff`, or `woff2`
+`--output FILE`:: Output file path
+`--optimize`:: Enable CFF optimization for OTF output
+`--named-instance INDEX`:: Use named instance by index
+`--list-instances`:: List available named instances
+`--validate`:: Validate font before generation
+`--dry-run`:: Preview instance without generating
+`--progress`:: Show progress during generation
+
+
+.Generate bold instance at wght=700
+[example]
+====
+[source,shell]
 ----
-# Convert with verbose output
-$ fontisan convert input.ttf --to otf --output output.otf --optimize --verbose
-
-# Validate the output
-$ fontisan validate output.otf
+$ fontisan instance variable.ttf --wght 700 --output bold.ttf
 
-# Check CharString structure
-$ fontisan info output.otf
+Generating instance... done
+Writing output... done
+Static font instance written to: bold.ttf
 ----
+====
 
-If validation fails, try:
-
-[source,bash]
+.Generate instance and convert to OTF
+[example]
+====
+[source,shell]
 ----
-# Disable optimization
-$ fontisan convert input.ttf --to otf --output output.otf
+$ fontisan instance variable.ttf --wght 300 --to otf --output light.otf
 
-# Use stack-aware mode for safer optimization
-$ fontisan convert input.ttf --to otf --output output.otf --optimize --stack-aware
+Generating instance... done
+Writing output... done
+Static font instance written to: light.otf
 ----
+====
 
-==== Using the CLI
-
-.Convert with subroutine optimization
+.Generate instance and convert to WOFF
 [example]
 ====
-[source,bash]
+[source,shell]
 ----
-# Enable optimization with default settings
-$ fontisan convert input.ttf --to otf --output output.otf --optimize --verbose
-
-Converting input.ttf to otf...
+$ fontisan instance variable.ttf --wght 600 --to woff --output semibold.woff
 
-=== Subroutine Optimization Results ===
-  Patterns found: 234
-  Patterns selected: 89
-  Subroutines generated: 89
-  Estimated bytes saved: 45,234
-  CFF bias: 107
-
-Conversion complete!
-  Input:  input.ttf (806.3 KB)
-  Output: output.otf (979.5 KB)
+Generating instance... done
+Writing output... done
+Static font instance written to: semibold.woff
 ----
 ====
 
-.SQLite optimization parameters
+.Generate instance with multiple axes
 [example]
 ====
-[source,bash]
+[source,shell]
 ----
-# Adjust pattern matching sensitivity
-$ fontisan convert input.ttf --to otf --output output.otf \
-  --optimize \
-  --min-pattern-length 15 \
-  --max-subroutines 10000 \
-  --verbose
+$ fontisan instance variable.ttf --wght 600 --wdth 75 --output condensed.ttf
 
-# Disable ordering optimization
-$ fontisan convert input.ttf --to otf --output output.otf \
-  --optimize \
-  --no-optimize-ordering
+Generating instance... done
+Writing output... done
+Static font instance written to: condensed.ttf
 ----
 ====
 
-Where,
-
-`--optimize`:: Enable subroutine optimization (default: false)
-`--min-pattern-length N`:: Minimum pattern length in bytes (default: 10)
-`--max-subroutines N`:: Maximum number of subroutines to generate (default: 65,535)
-`--optimize-ordering`:: Optimize subroutine ordering by frequency (default: true)
-`--verbose`:: Show detailed optimization statistics
-
-==== Stack-Aware Optimization
-
-===== General
-
-Stack-aware optimization is an advanced mode that ensures all extracted patterns are stack-neutral, guaranteeing 100% safety and reliability. Unlike normal byte-level pattern matching, stack-aware mode simulates CharString execution to track operand stack depth, only extracting patterns that maintain consistent stack state.
+.List available named instances
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --list-instances
 
-Key benefits:
+Available named instances:
 
-* **100% Reliability**: All patterns are validated to be stack-neutral
-* **No Stack Errors**: Eliminates stack underflow/overflow issues
-* **Faster Processing**: 6-12x faster than normal optimization due to early filtering
-* **Smaller Pattern Set**: Significantly fewer candidates reduce memory usage
+  [0] Instance 4
+    Coordinates:
+      wdth: 75.0
+      wght: 200.0
 
-Trade-offs:
+  [1] Instance 5
+    Coordinates:
+      wdth: 75.0
+      wght: 250.0
 
-* **Lower Compression**: ~6% reduction vs ~11% with normal mode
-* **Fewer Patterns**: Filters out 90%+ of raw patterns for safety
-* **Stack Validation Overhead**: Adds stack tracking during analysis
+  [2] Instance 6
+    Coordinates:
+      wdth: 75.0
+      wght: 300.0
+----
+====
 
-===== Using the CLI
+.Use named instance
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --named-instance 0 --output thin.ttf
+----
+====
 
-.Enable stack-aware optimization
+.Preview instance generation (dry-run)
 [example]
 ====
-[source,bash]
+[source,shell]
 ----
-# Convert with stack-aware optimization
-$ fontisan convert input.ttf --to otf --output output.otf \
-  --optimize \
-  --stack-aware \
-  --verbose
+$ fontisan instance variable.ttf --wght 700 --dry-run
 
-Converting input.ttf to otf...
+Dry-run mode: Preview of instance generation
 
-Analyzing CharString patterns (4515 glyphs)...
-  Found 8566 potential patterns
-Selecting optimal patterns...
-  Selected 832 patterns for subroutinization
-Building subroutines...
-  Generated 832 subroutines
-Rewriting CharStrings with subroutine calls...
-  Rewrote 4515 CharStrings
+Coordinates:
+  wght: 700.0
 
-Subroutine Optimization Results:
-  Patterns found: 8566
-  Patterns selected: 832
-  Subroutines generated: 832
-  Estimated bytes saved: 46,280
-  CFF bias: 0
+Output would be written to: variable-instance.ttf
+Output
 
-Conversion complete!
-  Input:  input.ttf (806.3 KB)
-  Output: output.otf (660.7 KB)
+ format: same as input
+
+Use without --dry-run to actually generate the instance.
 ----
 ====
 
-.SQLite stack-aware vs normal mode
-[example]
-====
-[source,bash]
-----
-# Use the comparison script
-$ ruby scripts/compare_stack_aware.rb input.ttf
 
-File Size Reduction:
-  Normal: 81.49 KB (11.27%)
-  Stack-Aware: 43.17 KB (6.13%)
+== Optical size information
 
-Processing Times:
-  Normal: 18.38 s
-  Stack-Aware: 1.54 s (12x faster)
+=== General
 
-Stack-Aware Efficiency: 52.97% of normal optimization
+Display optical size range from the OS/2 table for fonts designed for specific
+point sizes.
+
+=== Command-line usage
+
+Syntax:
+
+[source,shell]
+----
+$ fontisan optical-size FONT_FILE [--format FORMAT]
 ----
-====
 
 Where,
 
-`--stack-aware`:: Enable stack-aware pattern detection (default: false)
+`FONT_FILE`:: Path to the font file with optical sizing
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
 
-===== Using the Ruby API
 
-.Basic stack-aware optimization
+.Optical size information in Libertinus Serif Display
 [example]
 ====
-[source,ruby]
+[source,shell]
+----
+$ fontisan optical-size spec/fixtures/fonts/libertinus/ttf/LibertinusSerifDisplay-Regular.ttf
 ----
-require 'fontisan'
 
-# Load TrueType font
-font = Fontisan::FontLoader.load('input.ttf')
+[source,text]
+----
+Size range: [18, 72) pt  (source: OS/2_usLowerOpticalPointSize)
+----
+====
 
-# Convert with stack-aware optimization
-converter = Fontisan::Converters::OutlineConverter.new
-tables = converter.convert(font, {
-  target_format: :otf,
-  optimize_subroutines: true,
-  stack_aware: true  # Enable safe mode
-})
 
-# Access results
-optimization = tables.instance_variable_get(:@subroutine_optimization)
-puts "Patterns found: #{optimization[:pattern_count]}"
-puts "Stack-neutral patterns: #{optimization[:selected_count]}"
-puts "Processing time: #{optimization[:processing_time]}s"
+== List supported scripts
 
-# Write output
-Fontisan::FontWriter.write_to_file(
-  tables,
-  'output.otf',
-  sfnt_version: 0x4F54544F
-)
-----
-====
+=== General
+
+Show all scripts (writing systems) supported by the font, extracted from GSUB
+and GPOS tables. Useful for understanding language coverage.
 
-===== Technical Details
+=== Command-line usage
 
-Stack-aware mode uses a three-stage validation process:
+Syntax:
 
-[source]
+[source,shell]
 ----
-CharString Bytes → Stack Tracking → Pattern Validation → Safe Patterns
-    (Input)         (Simulate)       (Filter)           (Output)
+$ fontisan scripts FONT_FILE [--format FORMAT]
 ----
 
-**Stack Tracking**:
-
-. Simulates CharString execution without full interpretation
-. Records stack depth at each byte position
-. Handles 40+ Type 2 CharString operators with correct stack effects
-
-**Pattern Validation**:
+Where,
 
-. Checks if pattern start and end have same stack depth
-. Ensures no stack underflow during pattern execution
-. Verifies consistent results regardless of initial stack state
+`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
 
-**Stack-Neutral Pattern** criteria:
 
-[source]
+.Supported scripts in Libertinus Serif Regular
+[example]
+====
+[source,shell]
 ----
-Pattern is stack-neutral if:
-1. depth_at(pattern_start) == depth_at(pattern_end)
-2. No negative depth during pattern execution
-3. Pattern produces same result for any valid initial stack
+$ fontisan scripts spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
 ----
 
-**Example Stack-Neutral Pattern**:
-[source]
-----
-10 20 rmoveto  # Pushes 2 operands, consumes 2 → neutral
+[source,text]
 ----
+Script count: 5
 
-**Example Non-Neutral Pattern**:
-[source]
+DFLT  Default
+cyrl  Cyrillic
+grek  Greek
+hebr  Hebrew
+latn  Latin
 ----
-10 20 add  # Pushes 2, consumes 2
+====
 
-, produces 1 → NOT neutral
-----
 
-===== When to Use Stack-Aware Mode
+== List OpenType features
 
-**Recommended for**:
+=== General
 
-* Production font conversion where reliability is critical
-* Fonts that will undergo further processing
-* Web fonts where correctness matters more than minimal size
-* Situations where testing/validation is limited
+Show OpenType layout features (typography features like ligatures, kerning,
+small capitals) available for specific scripts or all scripts.
 
-**Normal mode acceptable for**:
+=== Command-line usage
 
-* Development/testing environments
-* When full validation will be performed post-conversion
-* Maximum compression is priority over guaranteed safety
+Syntax:
 
-==== Using the Ruby API
+[source,shell]
+----
+$ fontisan features FONT_FILE [--script SCRIPT] [--format FORMAT]
+----
 
-.Basic optimization
+Where,
+
+`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
+`SCRIPT`:: Optional 4-character script tag (e.g., `latn`, `cyrl`, `arab`). If not specified, shows features for all scripts
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+
+
+.OpenType features for Latin script
 [example]
 ====
-[source,ruby]
+[source,shell]
+----
+$ fontisan features spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --script latn
 ----
-require 'fontisan'
 
-# Load TrueType font
-font = Fontisan::FontLoader.load('input.ttf')
-
-# Convert with optimization
-converter = Fontisan::Converters::OutlineConverter.new
-tables = converter.convert(font, {
-  target_format: :otf,
-  optimize_subroutines: true
-})
-
-# Access optimization results
-optimization = tables.instance_variable_get(:@subroutine_optimization)
-puts "Patterns found: #{optimization[:pattern_count]}"
-puts "Selected: #{optimization[:selected_count]}"
-puts "Savings: #{optimization[:savings]} bytes"
+[source,text]
+----
+Script: latn
+Feature count: 4
 
-# Write output
-Fontisan::FontWriter.write_to_file(
-  tables,
-  'output.otf',
-  sfnt_version: 0x4F54544F
-)
+cpsp  Capital Spacing
+kern  Kerning
+mark  Mark Positioning
+mkmk  Mark to Mark Positioning
 ----
 ====
 
-.Custom optimization parameters
+
+.OpenType features for all scripts
 [example]
 ====
-[source,ruby]
+[source,shell]
 ----
-require 'fontisan'
-
-font = Fontisan::FontLoader.load('input.ttf')
-converter = Fontisan::Converters::OutlineConverter.new
-
-# Fine-tune optimization
-tables = converter.convert(font, {
-  target_format: :otf,
-  optimize_subroutines: true,
-  min_pattern_length: 15,
-  max_subroutines: 5000,
-  optimize_ordering: true,
-  verbose: true
-})
-
-# Analyze results
-optimization = tables.instance_variable_get(:@subroutine_optimization)
-if optimization[:selected_count] > 0
-  efficiency = optimization[:savings].to_f / optimization[:selected_count]
-  puts "Average savings per subroutine: #{efficiency.round(2)} bytes"
-end
+$ fontisan features spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
 ----
-====
 
-==== Technical Details
-
-The subroutine optimizer uses a four-stage pipeline:
-
-[source]
-----
-CharStrings → Pattern Analysis → Selection → Ordering → Metadata
-  (Input)      (Find repeats)    (Optimize)  (Frequency)  (Output)
+[source,text]
 ----
+Script: DFLT
+Feature count: 4
 
-**Pattern Analysis**:
+  cpsp  Capital Spacing
+  kern  Kerning
+  mark  Mark Positioning
+  mkmk  Mark to Mark Positioning
 
-. Extracts byte sequences from all CharStrings
-. Identifies repeating patterns across glyphs
-. Filters by minimum pattern length (default: 10 bytes)
-. Builds pattern frequency map
+Script: cyrl
+Feature count: 4
+
+  cpsp  Capital Spacing
+  kern  Kerning
+  mark  Mark Positioning
+  mkmk  Mark to Mark Positioning
 
-**Selection Algorithm**:
+Script: grek
+Feature count: 4
 
-. Calculates savings for each pattern: `frequency × (length - overhead)`
-. Ranks patterns by total savings (descending)
-. Selects top patterns up to `max_subroutines` limit
-. Ensures selected patterns don't exceed CFF limits
+  cpsp  Capital Spacing
+  kern  Kerning
+  mark  Mark Positioning
+  mkmk  Mark to Mark Positioning
 
-**Ordering Optimization**:
+Script: hebr
+Feature count: 2
 
-. Sorts subroutines by usage frequency (most used first)
-. Optimizes CFF bias calculation for better compression
-. Ensures subroutine indices fit within CFF constraints
+  mark  Mark Positioning
+  mkmk  Mark to Mark Positioning
 
-**CFF Bias Calculation**:
+Script: latn
+Feature count: 4
 
-[source]
-----
-Subroutine count    CFF Bias
------------------   ---------
-0-1239              107
-1240-33899          1131
-33900-65535         32768
+  cpsp  Capital Spacing
+  kern  Kerning
+  mark  Mark Positioning
+  mkmk  Mark to Mark Positioning
 ----
+====
 
-The bias value determines how subroutine indices are encoded in CharStrings, affecting the final size.
-
-=== Round-Trip Validation
 
-==== General
+== Dump raw table data
 
-Fontisan ensures high-fidelity font conversion through comprehensive round-trip validation. When converting between TrueType (TTF) and OpenType/CFF (OTF) formats, the validation system verifies that glyph geometry is preserved accurately.
+=== General
 
-Key validation features:
+Extract raw binary data from a specific OpenType table. Useful for detailed
+analysis or debugging font issues.
 
-* **Command-Level Precision**: Validates individual drawing commands (move, line, curve)
-* **Coordinate Tolerance**: Accepts ±2 pixels tolerance for rounding during conversion
-* **Format-Aware Comparison**: Handles differences between TrueType quadratic and CFF cubic curves
-* **Closepath Handling**: Smart detection of geometrically closed vs open contours
-* **100% Coverage**: All 4,515 glyphs validated in test fonts
+=== Command-line usage
 
-==== Technical Details
+TODO: should support output to file directly with `--output FILE`.
 
-Round-trip validation works by:
+Syntax:
 
-[source]
+[source,shell]
 ----
-Original TTF → Convert to CFF → Extract CFF → Compare Geometry
-    (Input)      (Encode)         (Decode)      (Validate)
+$ fontisan dump-table FONT_FILE TABLE_TAG
 ----
 
-**Validation Process**:
-
-. Extract glyph outlines from original TTF
-. Convert to CFF format with CharString encoding
-. Parse CFF CharStrings back to universal outlines
-. Compare geometry with coordinate tolerance (±2 pixels)
-
-**Format Differences Handled**:
+Where,
 
-* **Closepath**: CFF has implicit closepath, TTF has explicit
-* **Curve Types**: TrueType quadratic (`:quad_to`) vs CFF cubic (`:curve_to`)
-* **Coordinate Rounding**: Different number encoding causes minor differences
+`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
+`TABLE_TAG`:: Four-character table tag (e.g., `name`, `head`, `GSUB`, `GPOS`)
 
-**Validation Criteria**:
 
-[source]
+.Dump raw table data to files
+[example]
+====
+[source,shell]
 ----
-Geometry Match:
-1. Same bounding box (±2 pixel tolerance)
-2. Same number of path commands (excluding closepath)
-3. Same endpoint coordinates for curves (±2 pixels)
-4. Quadratic→cubic conversion accepted
+$ fontisan dump-table spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf name > name_table.bin
+$ fontisan dump-table spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf GPOS > gpos_table.bin
+$ fontisan dump-table spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf head > head_table.bin
 ----
 
-==== Test Coverage
-
-The validation suite tests:
-
-* **Without Optimization**: All glyphs convert correctly ✅
-* **With Optimization**: Pending fix for subroutine bug (91 glyphs affected)
-
-**Status**:
-```
-Round-trip validation: 100% passing (without optimization)
-Test suite: 2870/2870 passing, 15 pending (future features)
-```
-
-==== Known Issues
-
-**Integration Tests** (low priority):
-One bbox mismatch failure remains in integration tests. This is not a CharString parsing error but may be a rounding issue during conversion. The issue is documented and does not affect the core functionality. Round-trip validation for CharString parsing is now fully functional after v2.0.0-rc1 bug fixes.
-
-=== Current Limitations
-
-==== Features not yet implemented
-
-* **CFF Table Serialization**: While subroutine optimization calculates accurate space savings, the serialization of optimized CFF tables with subroutines is pending. Current output CFF tables function correctly but do not include generated subroutines.
-* **Hints**: TrueType instructions and CFF hints are not preserved during conversion
-* **CFF2**: Variable fonts using CFF2 tables are not supported
-
-==== Optimization Preview Mode
-
-The subroutine optimizer is currently in preview mode:
-
-* Pattern analysis and subroutine generation work correctly
-* Accurate space savings calculations are provided
-* Optimization results are stored in metadata
-* CFF table serialization with subroutines will be added in the next phase
-
-=== Planned Features
-
-==== Phase 2 (Current development phase)
-
-* CFF table serialization with subroutine support (in progress)
-* Hint preservation and conversion
-* CFF2 support for variable fonts
-* Round-trip conversion validation
-* Batch conversion support
+The output is binary data written directly to stdout, which can be redirected to
+a file for further analysis.
+====
 
 
-== Usage
+== Export font structure
 
-=== Command-line interface
+=== General
 
-==== Font information
+Export font structure to TTX (FontTools XML), YAML, or JSON formats for
+analysis, interchange, or version control. Supports selective table export and
+configurable binary data encoding.
 
-Extract comprehensive metadata from font files. This includes font names,
-version information, designer credits, vendor details, licensing information,
-and font metrics.
+=== Command-line usage
 
 Syntax:
 
 [source,shell]
 ----
-$ fontisan info FONT_FILE [--format FORMAT]
+$ fontisan export FONT_FILE [--output FILE] [--format FORMAT] [--tables TABLES] [--binary-format FORMAT]
 ----
 
 Where,
 
 `FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+`--output FILE`:: Output file path (default: stdout)
+`--format FORMAT`:: Export format: `yaml` (default), `json`, or `ttx`
+`--tables TABLES`:: Specific tables to export (space-separated list)
+`--binary-format FORMAT`:: Binary encoding: `hex` (default) or `base64`
 
 
-.Font information for Libertinus Serif Regular
+.Export font to YAML format
 [example]
 ====
 [source,shell]
 ----
-$ fontisan info spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
+$ fontisan export spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --output font.yaml
 
-Font type:                TrueType
-Family:                   Libertinus Serif
-Subfamily:                Regular
-Full name:                Libertinus Serif Regular
-PostScript name:          LibertinusSerif-Regular
-Version:                  Version 7.051;RELEASE
-Unique ID:                5.000;QUE ;LibertinusSerif-Regular
-Designer:                 Philipp H. Poll, Khaled Hosny
-Manufacturer:             Caleb Maclennan
-Vendor URL:               https://github.com/alerque/libertinus
-Vendor ID:                QUE
-License Description:      This Font Software is licensed under the SIL Open Font
-                          License, Version 1.1. This license is available with a
-                          FAQ at: https://openfontlicense.org
-License URL:              https://openfontlicense.org
-Font revision:            7.05099
-Permissions:              Installable
-Units per em:             1000
+# Output: font.yaml with complete font structure in YAML
 ----
 ====
 
-
-.Output in structured YAML format
+.Export specific tables to TTX format
 [example]
 ====
 [source,shell]
 ----
-$ fontisan info spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --format yaml
+$ fontisan export spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf \
+  --format ttx --tables head hhea maxp name --output font.ttx
 ----
 
-[source,yaml]
+Exports only the specified tables in FontTools TTX XML format for compatibility
+with fonttools.
+====
+
+.Export to JSON with base64 binary encoding
+[example]
+====
+[source,shell]
 ----
-font_format: truetype
-is_variable: false
-family_name: Libertinus Serif
-subfamily_name: Regular
-full_name: Libertinus Serif Regular
-postscript_name: LibertinusSerif-Regular
-version: Version 7.051;RELEASE
-unique_id: 5.000;QUE ;LibertinusSerif-Regular
-designer: Philipp H. Poll, Khaled Hosny
-manufacturer: Caleb Maclennan
-vendor_url: https://github.com/alerque/libertinus
-vendor_id: QUE
-license_description: 'This Font Software is licensed under the SIL Open Font License,
-  Version 1.1. This license is available with a FAQ at: https://openfontlicense.org'
-license_url: https://openfontlicense.org
-font_revision: 7.050994873046875
-permissions: Installable
-units_per_em: 1000
+$ fontisan export font.ttf --format json --binary-format base64 --output font.json
 ----
+
+Uses base64 encoding for binary data instead of hexadecimal, useful for
+JSON-based workflows.
 ====
 
 
-==== List OpenType tables
+== Version information
 
-Display the font's table directory, showing all OpenType tables with their
-sizes, offsets, and checksums. Useful for understanding font structure and
-verifying table integrity.
+=== General
 
-Syntax:
+Display the Fontisan version.
+
+=== Command-line usage
 
 [source,shell]
 ----
-$ fontisan tables FONT_FILE [--format FORMAT]
+fontisan version
 ----
 
-Where,
 
-`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+== Font collections
 
-.List of OpenType tables in Libertinus Serif Regular
-[example]
-====
-[source,shell]
-----
-$ fontisan tables spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
-----
+=== General
 
-[source,text]
-----
-SFNT Version: TrueType (0x00010000)
-Number of tables: 16
+Fontisan provides comprehensive tools for managing TrueType Collections (TTC)
+and OpenType Collections (OTC). You can list fonts in a collection, extract
+individual fonts, unpack entire collections, and validate collection integrity.
 
-Tables:
-  GDEF         834 bytes  (offset: 542156, checksum: 0x429C5C0C)
-  GPOS       17870 bytes  (offset: 542992, checksum: 0x29CE4200)
-  OS/2          96 bytes  (offset: 392, checksum: 0x4830F1C3)
-  cmap        3620 bytes  (offset: 11412, checksum: 0x03AD3899)
-  cvt          248 bytes  (offset: 18868, checksum: 0x3098127E)
-  fpgm        3596 bytes  (offset: 15032, checksum: 0x622F0781)
-  gasp           8 bytes  (offset: 542148, checksum: 0x00000010)
-  glyf      484900 bytes  (offset: 30044, checksum: 0x0FF34594)
-  head          54 bytes  (offset: 268, checksum: 0x18F5BDD0)
-  hhea          36 bytes  (offset: 324, checksum: 0x191E2264)
-  hmtx       10924 bytes  (offset: 488, checksum: 0x1F9D892B)
-  loca       10928 bytes  (offset: 19116, checksum: 0x230B1A58)
-  maxp          32 bytes  (offset: 360, checksum: 0x0EF919E7)
-  name         894 bytes  (offset: 514944, checksum: 0x4E9173E6)
-  post       26308 bytes  (offset: 515840, checksum: 0xE3D70231)
-  prep         239 bytes  (offset: 18628, checksum: 0x8B4AB356)
+
+=== List fonts
+
+==== General
+
+List all fonts in a TrueType Collection (TTC) or OpenType Collection (OTC), with
+their index, family name, and style.
+
+==== Command-line usage
+
+[source,shell]
+----
+$ fontisan ls FONT.{ttc,otc}
 ----
-====
 
-.Output in structured YAML format
+NOTE: In `extract_ttc`, this was done with `extract_ttc --list FONT.ttc`.
+
+
+.List collection contents
 [example]
 ====
 [source,shell]
 ----
-$ fontisan tables spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --format yaml
+# List all fonts in a TTC with detailed info
+$ fontisan ls spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc
+
+Font 0: Noto Serif CJK JP
+  Family: Noto Serif CJK JP
+  Subfamily: Regular
+  PostScript: NotoSerifCJKJP-Regular
+
+Font 1: Noto Serif CJK KR
+  Family: Noto Serif CJK KR
+  Subfamily: Regular
+  PostScript: NotoSerifCJKKR-Regular
+
+Font 2: Noto Serif CJK SC
+  Family: Noto Serif CJK SC
+  Subfamily: Regular
+  PostScript: NotoSerifCJKSC-Regular
+
+Font 3: Noto Serif CJK TC
+  Family: Noto Serif CJK TC
+  Subfamily: Regular
+  PostScript: NotoSerifCJKTC-Regular
 ----
+====
 
-[source,yaml]
+
+=== Show collection info
+
+==== General
+
+Show detailed information about a TrueType Collection (TTC) or OpenType Collection
+(OTC), including the number of fonts and metadata for each font.
+
+==== Command-line usage
+
+[source,shell]
+----
+$ fontisan info FONT.{ttc,otc}
 ----
+
+NOTE: In `extract_ttc`, this was done with `extract_ttc --info FONT.ttc`.
+
+.Get collection information
+[example]
+====
+[source,shell]
+----
+# Detailed collection analysis
+$ fontisan info spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc --format yaml
+
 ---
-sfnt_version: TrueType (0x00010000)
-num_tables: 16
-tables:
-- tag: GDEF
-  length: 834
-  offset: 542156
-  checksum: 1117543436
-- tag: GPOS
-  length: 17870
-  offset: 542992
-  checksum: 701383168
-- tag: OS/2
-  length: 96
-  offset: 392
-  checksum: 1211167171
-- tag: cmap
-  length: 3620
-  offset: 11412
-  checksum: 61683865
-- tag: 'cvt '
-  length: 248
-  offset: 18868
-  checksum: 815272574
-- tag: fpgm
-  length: 3596
-  offset: 15032
-  checksum: 1647249281
-----
-====
-
-==== List glyph names
+collection_type: ttc
+font_count: 4
+fonts:
+- index: 0
+  family_name: Noto Serif CJK JP
+  subfamily_name: Regular
+  postscript_name: NotoSerifCJKJP-Regular
+  font_format: opentype
+- index: 1
+  family_name: Noto Serif CJK KR
+  subfamily_name: Regular
+  postscript_name: NotoSerifCJKKR-Regular
+  font_format: opentype
+- index: 2
+  family_name: Noto Serif CJK SC
+  subfamily_name: Regular
+  postscript_name: NotoSerifCJKSC-Regular
+  font_format: opentype
+- index: 3
+  family_name: Noto Serif CJK TC
+  subfamily_name: Regular
+  postscript_name: NotoSerifCJKTC-Regular
+  font_format: opentype
+----
+====
 
-Show all glyph names defined in the font's post table. Each glyph is listed with
-its index and name, useful for understanding the font's character coverage.
 
-Syntax:
+=== Unpack fonts
+
+==== General
+
+Extract all fonts from a TrueType Collection (TTC) or OpenType Collection (OTC)
+to a specified output directory.
+
+==== Command-line usage
 
 [source,shell]
 ----
-$ fontisan glyphs FONT_FILE [--format FORMAT]
+$ fontisan unpack FONT.{ttc,otc} OUTPUT_DIR
 ----
 
-Where,
+NOTE: In `extract_ttc`, this was done with `extract_ttc --unpack FONT.ttc OUTPUT_DIR`.
 
-`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+.Extract fonts from collection
+[example]
+====
+[source,shell]
+----
+# Extract all fonts from collection
+$ fontisan unpack family.ttc --output-dir extracted/
 
+Collection unpacked successfully:
+  Input: family.ttc
+  Output directory: extracted/
+  Fonts extracted: 3/3
+  - font1.ttf (89.2 KB)
+  - font2.ttf (89.2 KB)
+  - font3.ttf (67.4 KB)
 
-.List of glyph names in Libertinus Serif Regular
-[example]
+# Extract specific font with format conversion
+$ fontisan unpack family.ttc --output-dir extracted/ --font-index 0 --format woff2
+----
 ====
+
+=== Extract specific font
+
+==== General
+
+Extract a specific font from a TrueType Collection (TTC) or OpenType Collection
+(OTC) by its index.
+
+==== Command-line usage
+
 [source,shell]
 ----
-$ fontisan glyphs spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
+$ fontisan unpack FONT.{ttc,otc} --font-index INDEX OUTPUT.{ttf,otf}
 ----
 
-[source,text]
+NOTE: In `extract_ttc`, this was done with `extract_ttc --font-index INDEX FONT.ttc OUTPUT.ttf`.
+
+.Extract with validation
+[example]
+====
+[source,shell]
 ----
-Glyph count: 2731
-Source: post_2.0
+# Extract and validate simultaneously
+$ fontisan unpack spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc extracted_fonts/ --validate
 
-Glyph names:
-      0  .notdef
-      1  space
-      2  exclam
-      3  quotedbl
-      4  numbersign
-      5  dollar
-      6  percent
-      7  ampersand
-      8  quotesingle
-      9  parenleft
-     10  parenright
-     11  asterisk
-     12  plus
-     13  comma
-     14  hyphen
-     15  period
-     16  slash
-     17  zero
-     18  one
-     19  two
-     20  three
-     ...
+Extracting font 0: Noto Serif CJK JP → extracted_fonts/NotoSerifCJKJP-Regular.ttf
+Extracting font 1: Noto Serif CJK KR → extracted_fonts/NotoSerifCJKKR-Regular.ttf
+Extracting font 2: Noto Serif CJK SC → extracted_fonts/NotoSerifCJKSC-Regular.ttf
+Extracting font 3: Noto Serif CJK TC → extracted_fonts/NotoSerifCJKTC-Regular.ttf
+
+Validation: All fonts extracted successfully
 ----
 ====
 
-==== Show Unicode mappings
+=== Pack fonts into collection
 
-Display Unicode codepoint to glyph index mappings from the cmap table. Shows
-which glyphs are assigned to which Unicode characters.
+==== General
 
-Syntax:
+Create a new TrueType Collection (TTC) or OpenType Collection (OTC) from multiple
+font files. Fontisan optimizes the collection by deduplicating shared tables
+to reduce file size.
+
+==== Command-line usage
 
+.Create TTC collection from multiple fonts
 [source,shell]
 ----
-$ fontisan unicode FONT_FILE [--format FORMAT]
+# Pack fonts into TTC with table sharing optimization
+$ fontisan pack font1.ttf font2.ttf font3.ttf --output family.ttc --analyze
+
+Collection Analysis:
+Total fonts: 3
+Shared tables: 12
+Potential space savings: 45.2 KB
+Table sharing: 68.5%
+
+Collection created successfully:
+  Output: family.ttc
+  Format: TTC
+  Fonts: 3
+  Size: 245.8 KB
+  Space saved: 45.2 KB
+  Sharing: 68.5%
 ----
 
-Where,
+.Create OTC collection from OpenType fonts
+[source,shell]
+----
+$ fontisan pack Regular.otf Bold.otf Italic.otf --output family.otc --format otc
+----
 
-`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
 
+=== Validate collection
+
+==== General
+
+Validate the structure and checksums of a TrueType Collection (TTC) or OpenType
+Collection (OTC).
+
+==== Command-line usage
 
-.Unicode to glyph mappings in Libertinus Serif Regular
-[example]
-====
 [source,shell]
 ----
-$ fontisan unicode spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
+$ fontisan validate FONT.{ttc,otc}
+----
+
+NOTE: In `extract_ttc`, this was done with `extract_ttc --validate FONT.ttc`.
+
+
+== Advanced features
+
+Fontisan provides capabilities:
+
+.Font analysis and inspection
+* Extract OpenType tables with checksums and offsets
+* Display Unicode mappings and glyph names
+* Analyze variable font axes and instances
+* Show supported scripts and OpenType features
+* Dump raw binary table data
+
+.Format conversion and subsetting
+* Convert between TTF, OTF, WOFF, and WOFF2 formats
+* Create font subsets with specific glyph ranges
+* Validate font structure and integrity
+* Generate SVG representations of glyphs
+
+.Collection creation
+* Build new TTC files from individual fonts
+* Optimize collection with table deduplication
+* Pack fonts with shared tables for smaller file sizes
+
+For complete migration guide, see link:docs/EXTRACT_TTC_MIGRATION.md[extract_ttc Migration Guide].
+
+
+
+
+== Loading modes
+
+=== General
+
+Fontisan provides a flexible loading modes architecture that enables efficient
+font parsing for different use cases.
+
+The system supports two distinct modes:
+
+`:full` mode:: (default) Loads all tables in the font for complete analysis and
+manipulation
+
+`:metadata` mode:: Loads only metadata tables needed for font identification and
+metrics (similar to `otfinfo` functionality). This mode is around 5x faster
+than full parsing and uses significantly less memory.
+
+This architecture is particularly useful for software that only
+needs basic font information without full parsing overhead, such as
+font indexing systems or font discovery tools.
+
+This mode was developed to improve performance in font indexing in the
+https://github.com/fontist/fontist[Fontist] library, where system fonts
+need to be scanned quickly without loading unnecessary data.
+
+A font file opened in `:metadata` mode will only have a subset of tables
+loaded, and attempts to access non-loaded tables will return `nil`.
+
+[source,ruby]
+----
+font = Fontisan::FontLoader.load('font.ttf', mode: :metadata)
+
+# Check table availability before accessing
+font.table_available?("name")  # => true
+font.table_available?("GSUB")  # => false
+
+# Access allowed tables
+font.table("name")  # => Works
+font.table("head")  # => Works
+
+# Restricted tables return nil
+font.table("GSUB")  # => nil (not loaded in metadata mode)
+----
+
+You can also set loading modes via the environment:
+
+[source,ruby]
 ----
+# Set defaults via environment
+ENV['FONTISAN_MODE'] = 'metadata'
+ENV['FONTISAN_LAZY'] = 'false'
+
+# Uses environment settings
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Explicit parameters override environment
+font = Fontisan::FontLoader.load('font.ttf', mode: :full)
+----
+
+The loading mode can be queried at any time.
+
+[source,ruby]
+----
+# Mode stored as font property
+font.loading_mode  # => :metadata or :full
+
+# Table availability checked before access
+font.table_available?(tag)  # => boolean
+
+# Access restricted based on mode
+font.table(tag)  # => Returns table or raises error
+----
+
+
+
+=== Metadata mode
+
+Loads only 6 tables (name, head, hhea, maxp, OS/2, post) instead of 15-20 tables.
+
+.Metadata mode: Fast loading for font identification
+[source,ruby]
+----
+font = Fontisan::FontLoader.load('font.ttf', mode: :metadata)
+puts font.family_name          # => "Arial"
+puts font.subfamily_name       # => "Regular"
+puts font.post_script_name     # => "ArialMT"
+----
+
+Tables loaded:
+
+name:: Font names and metadata
+head:: Font header with global metrics
+hhea:: Horizontal header with line spacing
+maxp:: Maximum profile with glyph count
+OS/2:: OS/2 and Windows metrics
+post:: PostScript information
+
+
+In metadata mode, these convenience methods provide direct access to name table
+fields:
+
+`family_name`:: Font family name (nameID 1)
+`subfamily_name`:: Font subfamily/style name (nameID 2)
+`full_name`:: Full font name (nameID 4)
+`post_script_name`:: PostScript name (nameID 6)
+`preferred_family_name`:: Preferred family name (nameID 16, may be nil)
+`preferred_subfamily_name`:: Preferred subfamily name (nameID 17, may be nil)
+`units_per_em`:: Units per em from head table
+
+
+=== Full mode
+
+Loads all tables in the font for complete analysis and manipulation.
+
+.Full mode: Complete font analysis
+[source,ruby]
+----
+font = Fontisan::FontLoader.load('font.ttf', mode: :full)
+font.table("GSUB")  # => Available
+font.table("GPOS")  # => Available
+
+# Check which mode is active
+puts font.loading_mode  # => :metadata or :full
+----
+
+Tables loaded:
+
+* All tables in the font
+* Including GSUB, GPOS, cmap, glyf/CFF, etc.
+
+=== Lazy loading option
+
+Fontisan supports lazy loading of tables in both `:metadata` and `:full` modes.
+When lazy loading is enabled (optional), tables are only parsed when accessed.
+
+Options:
+
+`false`:: (default) Eager loading. All tables for the selected mode are parsed
+upfront.
+
+`true`:: Lazy loading enabled. Tables are parsed on-demand.
+
+[source,ruby]
+----
+# Metadata mode with lazy loading (default, fastest)
+font = Fontisan::FontLoader.load('font.ttf', mode: :metadata, lazy: true)
+
+# Metadata mode with eager loading (loads all metadata tables upfront)
+font = Fontisan::FontLoader.load('font.ttf', mode: :metadata, lazy: false)
+
+# Full mode with lazy loading (tables loaded on-demand)
+font = Fontisan::FontLoader.load('font.ttf', mode: :full, lazy: true)
 
-[source,text]
+# Full mode with eager loading (all tables loaded upfront)
+font = Fontisan::FontLoader.load('font.ttf', mode: :full, lazy: false)
 ----
-Unicode mappings: 2382
 
-U+0020  glyph 1  space
-U+0021  glyph 2  exclam
-U+0022  glyph 3  quotedbl
-U+0023  glyph 4  numbersign
-U+0024  glyph 5  dollar
-U+0025  glyph 6  percent
-U+0026  glyph 7  ampersand
-U+0027  glyph 8  quotesingle
-U+0028  glyph 9  parenleft
-U+0029  glyph 10  parenright
-U+002A  glyph 11  asterisk
-U+002B  glyph 12  plus
-U+002C  glyph 13  comma
-U+002D  glyph 14  hyphen
-U+002E  glyph 15  period
-U+002F  glyph 16  slash
-U+0030  glyph 17  zero
-U+0031  glyph 18  one
-...
-----
-====
 
-==== Variable font information
 
-Display variation axes and named instances for variable fonts. Shows the design
-space and predefined styles available in the font.
 
-Syntax:
+== Outline format conversion
 
-[source,shell]
-----
-$ fontisan variable FONT_FILE [--format FORMAT]
-----
+=== General
 
-Where,
+Fontisan supports bidirectional conversion between TrueType (TTF) and
+OpenType/CFF (OTF) outline formats through the Fontist universal outline model
+(UOM).
 
-`FONT_FILE`:: Path to the variable font file
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+The outline converter enables transformation between glyph outline formats:
 
+TrueType (TTF):: Uses quadratic Bézier curves stored in glyf/loca tables
+OpenType/CFF (OTF):: Uses cubic Bézier curves stored in CFF table
 
-.Variable font axes and instances in Mona Sans
-[example]
-====
-[source,shell]
-----
-$ fontisan variable spec/fixtures/fonts/MonaSans/variable/MonaSans[wdth,wght].ttf
-----
+Conversion uses a format-agnostic universal outline model as an intermediate
+representation, ensuring high-quality results while preserving glyph metrics and
+bounding boxes.
 
-[source,text]
-----
-Axis 0:                 wdth
-Axis 0 name:            Width
-Axis 0 range:           75 125
-Axis 0 default:         100
-Axis 1:                 wght
-Axis 1 name:            Weight
-Axis 1 range:           200 900
-Axis 1 default:         400
-Instance 0 name:        Mona Sans Narrow Thin
-Instance 0 position:    75 200
-Instance 1 name:        Mona Sans Narrow ExtraLight
-Instance 1 position:    75 250
-Instance 2 name:        Mona Sans Narrow Light
-Instance 2 position:    75 300
-...
-----
-====
 
-==== Optical size information
+=== Convert between TTF and OTF
 
-Display optical size range from the OS/2 table for fonts designed for specific
-point sizes.
+==== Command-line usage
 
 Syntax:
 
-[source,shell]
+[source,bash]
 ----
-$ fontisan optical-size FONT_FILE [--format FORMAT]
+$ fontisan convert INPUT_FONT --to FORMAT --output OUTPUT_FONT
 ----
 
 Where,
 
-`FONT_FILE`:: Path to the font file with optical sizing
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+`INPUT_FONT`:: Path to the input font file (TTF or OTF)
+`FORMAT`:: Target format:
+`ttf`, `truetype`::: TrueType format
+`otf`, `opentype`, `cff`::: OpenType/CFF format
+`OUTPUT_FONT`:: Path to the output font file
 
 
-.Optical size information in Libertinus Serif Display
-[example]
-====
-[source,shell]
-----
-$ fontisan optical-size spec/fixtures/fonts/libertinus/ttf/LibertinusSerifDisplay-Regular.ttf
+[source,bash]
 ----
+# Convert TrueType font to OpenType/CFF
+fontisan convert input.ttf --to otf --output output.otf
 
-[source,text]
-----
-Size range: [18, 72) pt  (source: OS/2_usLowerOpticalPointSize)
+# Convert OpenType/CFF font to TrueType
+fontisan convert input.otf --to ttf --output output.ttf
 ----
-====
 
-==== List supported scripts
 
-Show all scripts (writing systems) supported by the font, extracted from GSUB
-and GPOS tables. Useful for understanding language coverage.
+==== Ruby API usage
 
-Syntax:
+Basic conversion with OutlineConverter:
 
-[source,shell]
-----
-$ fontisan scripts FONT_FILE [--format FORMAT]
+[source,ruby]
 ----
+require 'fontisan'
 
-Where,
+# Load a TrueType font
+font = Fontisan::FontLoader.load('input.ttf')
 
-`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+# Convert to OpenType/CFF
+converter = Fontisan::Converters::OutlineConverter.new
+tables = converter.convert(font, target_format: :otf)
 
+# Write output
+Fontisan::FontWriter.write_to_file(
+  tables,
+  'output.otf',
+  sfnt_version: 0x4F54544F  # 'OTTO' for OpenType/CFF
+)
+----
 
-.Supported scripts in Libertinus Serif Regular
-[example]
-====
-[source,shell]
+Using FormatConverter:
+
+[source,ruby]
 ----
-$ fontisan scripts spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
+require 'fontisan'
+
+# Load font
+font = Fontisan::FontLoader.load('input.ttf')
+
+# Convert using high-level API
+converter = Fontisan::Converters::FormatConverter.new
+if converter.supported?(:ttf, :otf)
+  tables = converter.convert(font, :otf)
+
+  # Write output
+  Fontisan::FontWriter.write_to_file(
+    tables,
+    'output.otf',
+    sfnt_version: 0x4F54544F
+  )
+end
 ----
 
-[source,text]
+To check supported conversions:
+
+[source,ruby]
 ----
-Script count: 5
+converter = Fontisan::Converters::FormatConverter.new
 
-DFLT  Default
-cyrl  Cyrillic
-grek  Greek
-hebr  Hebrew
-latn  Latin
+# Check if conversion is supported
+converter.supported?(:ttf, :otf)  # => true
+converter.supported?(:otf, :ttf)  # => true
+
+# Get all supported conversions
+converter.all_conversions
+# => [{from: :ttf, to: :otf}, {from: :otf, to: :ttf}, ...]
+
+# Get supported targets for a source format
+converter.supported_targets(:ttf)
+# => [:ttf, :otf, :woff2, :svg]
 ----
-====
 
-==== List OpenType features
 
-Show OpenType layout features (typography features like ligatures, kerning,
-small capitals) available for specific scripts or all scripts.
+=== Validation
 
-Syntax:
+Font integrity validation is enabled by default for all conversions.
 
-[source,shell]
+The validator ensures proper OpenType checksum calculation including correct
+handling of the head table's checksumAdjustment field per the OpenType
+specification.
+
+After conversion, validate the output font:
+
+[source,bash]
 ----
-$ fontisan features FONT_FILE [--script SCRIPT] [--format FORMAT]
+fontisan validate output.otf
+fontisan info output.otf
+fontisan tables output.otf
 ----
 
-Where,
 
-`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`SCRIPT`:: Optional 4-character script tag (e.g., `latn`, `cyrl`, `arab`). If not specified, shows features for all scripts
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+== Technical details of outline conversion
 
+=== General
 
-.OpenType features for Latin script
-[example]
-====
-[source,shell]
+The converter uses a three-stage pipeline:
+
+[source]
 ----
-$ fontisan features spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --script latn
+Source Format         Universal Outline         Target Format
+-------------         ------------------        -------------
+TrueType (glyf)  →→→  Command-based model  →→→  OpenType/CFF
+Quadratic curves      Path representation        Cubic curves
+On/off-curve pts      (format-agnostic)         CharStrings
+Delta encoding        Bounding boxes             Type 2 operators
+                      Metrics                    Compact encoding
 ----
 
-[source,text]
-----
-Script: latn
-Feature count: 4
+=== Conversion steps
 
-cpsp  Capital Spacing
-kern  Kerning
-mark  Mark Positioning
-mkmk  Mark to Mark Positioning
-----
-====
+TTF → OTF conversion:
 
+. Extract glyphs from glyf/loca tables
+. Convert quadratic Bézier curves to universal outline format
+. Build CFF table with CharStrings INDEX
+. Update maxp table to version 0.5 (CFF format)
+. Update head table (clear indexToLocFormat)
+. Remove glyf/loca tables
+. Preserve all other tables
 
-.OpenType features for all scripts
-[example]
-====
-[source,shell]
-----
-$ fontisan features spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
+OTF → TTF conversion:
+
+. Extract CharStrings from CFF table
+. Convert cubic Bézier curves to universal outline format
+. Convert cubic curves to quadratic using adaptive subdivision
+. Build glyf and loca tables with optimal format selection
+. Update maxp table to version 1.0 (TrueType format)
+. Update head table (set indexToLocFormat)
+. Remove CFF table
+. Preserve all other tables
+
+=== Curve conversion
+
+**Quadratic to cubic** (lossless):
+
+[source]
 ----
+Given quadratic curve with control point Q:
+  P0 (start), Q (control), P2 (end)
 
-[source,text]
+Calculate cubic control points:
+  CP1 = P0 + (2/3) × (Q - P0)
+  CP2 = P2 + (2/3) × (Q - P2)
+
+Result: Exact mathematical equivalent
 ----
-Script: DFLT
-Feature count: 4
 
-  cpsp  Capital Spacing
-  kern  Kerning
-  mark  Mark Positioning
-  mkmk  Mark to Mark Positioning
+**Cubic to quadratic** (adaptive):
 
-Script: cyrl
-Feature count: 4
+[source]
+----
+Given cubic curve with control points:
+  P0 (start), CP1, CP2, P3 (end)
 
-  cpsp  Capital Spacing
-  kern  Kerning
-  mark  Mark Positioning
-  mkmk  Mark to Mark Positioning
+Use adaptive subdivision algorithm:
+  1. Estimate error of quadratic approximation
+  2. If error > threshold (0.5 units):
+     - Subdivide cubic curve at midpoint
+     - Recursively convert each half
+  3. Otherwise: Output quadratic approximation
+
+Result: High-quality approximation with < 0.5 unit deviation
+----
 
-Script: grek
-Feature count: 4
+=== Compound glyph support
 
-  cpsp  Capital Spacing
-  kern  Kerning
-  mark  Mark Positioning
-  mkmk  Mark to Mark Positioning
+==== General
 
-Script: hebr
-Feature count: 2
+Fontisan fully supports compound (composite) glyphs in both conversion directions:
 
-  mark  Mark Positioning
-  mkmk  Mark to Mark Positioning
+* **TTF → OTF**: Compound glyphs are decomposed into simple outlines with transformations applied
+* **OTF → TTF**: CFF glyphs are converted to simple TrueType glyphs
 
-Script: latn
-Feature count: 4
+==== Decomposition process
 
-  cpsp  Capital Spacing
-  kern  Kerning
-  mark  Mark Positioning
-  mkmk  Mark to Mark Positioning
-----
-====
+When converting TTF to OTF, compound glyphs undergo the following process:
 
-==== Dump raw table data
+. Detected from glyf table flags (numberOfContours = -1)
+. Components recursively resolved (handling nested compound glyphs)
+. Transformation matrices applied to each component (translation, scale, rotation)
+. All components merged into a single simple outline
+. Converted to CFF CharString format
 
-Extract raw binary data from a specific OpenType table. Useful for detailed
-analysis or debugging font issues.
+This ensures that all glyphs render identically while maintaining proper metrics
+and bounding boxes.
 
-Syntax:
+==== Technical implementation
 
-[source,shell]
-----
-$ fontisan dump-table FONT_FILE TABLE_TAG
+Compound glyphs reference other glyphs by index and apply 2×3 affine
+transformation matrices:
+
+[source]
 ----
+x' = a*x + c*y + e
+y' = b*x + d*y + f
 
-Where,
+Where:
+- a, d: Scale factors for x and y axes
+- b, c: Rotation/skew components
+- e, f: Translation offsets (x, y position)
+----
 
-`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`TABLE_TAG`:: Four-character table tag (e.g., `name`, `head`, `GSUB`, `GPOS`)
+The resolver handles:
 
+* Simple glyphs referenced by compounds
+* Nested compound glyphs (compounds referencing other compounds)
+* Circular reference detection with maximum recursion depth (32 levels)
+* Complex transformation matrices (uniform scale, x/y scale, full 2×2 matrix)
 
-.Dump raw table data to files
-[example]
-====
-[source,shell]
-----
-$ fontisan dump-table spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf name > name_table.bin
-$ fontisan dump-table spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf GPOS > gpos_table.bin
-$ fontisan dump-table spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf head > head_table.bin
-----
+=== Subroutine optimization
 
-The output is binary data written directly to stdout, which can be redirected to a file for further analysis.
-====
+==== General
 
-==== Export font structure
+When converting TrueType (TTF) to OpenType/CFF (OTF), Fontisan can automatically
+generate CFF subroutines to reduce file size.
 
-Export font structure to TTX (FontTools XML), YAML, or JSON formats for analysis,
-interchange, or version control. Supports selective table export and configurable
-binary data encoding.
+Subroutines extract repeated CharString patterns across glyphs and store them
+once, significantly reducing CFF table size while maintaining identical glyph
+rendering.
 
-Syntax:
+Key features:
 
-[source,shell]
-----
-$ fontisan export FONT_FILE [--output FILE] [--format FORMAT] [--tables TABLES] [--binary-format FORMAT]
-----
+* Pattern analysis: Analyzes byte sequences across all CharStrings to identify repeating patterns
+* Frequency-based selection: Prioritizes patterns that provide maximum space savings
+* Configurable thresholds: Customizable minimum pattern length and maximum subroutine count
+* Ordering optimization: Automatically orders subroutines by frequency for better compression
 
-Where,
+Typical space savings: 30-50% reduction in CFF table size for fonts with similar
+glyph shapes.
 
-`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`--output FILE`:: Output file path (default: stdout)
-`--format FORMAT`:: Export format: `yaml` (default), `json`, or `ttx`
-`--tables TABLES`:: Specific tables to export (space-separated list)
-`--binary-format FORMAT`:: Binary encoding: `hex` (default) or `base64`
+NOTE: Current implementation calculates accurate optimization metrics but does
+not modify the output CFF table. Full CFF serialization with subroutines will be
+available in the next development phase.
 
+==== Edge cases
 
-.Export font to YAML format
-[example]
-====
-[source,shell]
-----
-$ fontisan export spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --output font.yaml
+The optimizer correctly handles:
 
-# Output: font.yaml with complete font structure in YAML
-----
-====
+* Multi-byte numbers: Number encodings from 1-5 bytes (CFF Type 2 format)
+* Two-byte operators: Operators with 0x0c prefix (e.g., `div` in `lib/fontisan/tables/cff/charstring.rb`, `flex` in `lib/fontisan/tables/cff/charstring.rb`)
+* Overlapping patterns: Multiple patterns at same byte positions
+* Stack-neutral validation: Patterns verified to maintain consistent stack state
 
-.Export specific tables to TTX format
-[example]
-====
-[source,shell]
-----
-$ fontisan export spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf \
-  --format ttx --tables head hhea maxp name --output font.ttx
-----
+==== Technical details
 
-Exports only the specified tables in FontTools TTX XML format for compatibility
-with fonttools.
-====
+The subroutine optimizer uses a four-stage pipeline:
 
-.Export to JSON with base64 binary encoding
-[example]
-====
-[source,shell]
+[source]
 ----
-$ fontisan export font.ttf --format json --binary-format base64 --output font.json
+CharStrings → Pattern Analysis → Selection → Ordering → Metadata
+  (Input)      (Find repeats)    (Optimize)  (Frequency)  (Output)
 ----
 
-Uses base64 encoding for binary data instead of hexadecimal, useful for
-JSON-based workflows.
-====
-
-==== General options
+**Pattern analysis**:
 
-All commands support these options:
-
-`--format FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+. Extracts byte sequences from all CharStrings
+. Identifies repeating patterns across glyphs
+. Filters by minimum pattern length (default: 10 bytes)
+. Builds pattern frequency map
 
-`--font-index INDEX`:: Font index for TTC files (default: 0)
+**Selection algorithm**:
 
-`--verbose`:: Enable verbose output
+. Calculates savings for each pattern: `frequency × (length - overhead)`
+. Ranks patterns by total savings (descending)
+. Selects top patterns up to `max_subroutines` limit
+. Ensures selected patterns don't exceed CFF limits
 
-`--quiet`:: Suppress non-error output
+**Ordering optimization**:
 
-==== Version information
+. Sorts subroutines by usage frequency (most used first)
+. Optimizes CFF bias calculation for better compression
+. Ensures subroutine indices fit within CFF constraints
 
-Display the Fontisan version:
+**CFF bias calculation**:
 
-[source,shell]
+[source]
 ----
-fontisan version
+Subroutine count    CFF Bias
+-----------------   ---------
+0-1239              107
+1240-33899          1131
+33900-65535         32768
 ----
 
+The bias value determines how subroutine indices are encoded in CharStrings,
+affecting the final size.
 
-==== Font collections
 
-===== List fonts
+==== Troubleshooting
 
-List all fonts in a TrueType Collection (TTC) or OpenType Collection (OTC), with
-their index, family name, and style.
+If you encounter CharString parsing errors after optimization:
 
-[source,shell]
+. Verify bias calculation: Ensure bias matches CFF specification (107, 1131, or 32768)
+. Check operator boundaries: Patterns should only be extracted at valid boundaries
+. Ensure no overlaps: Multiple patterns should not occupy same byte positions
+. Enable verbose mode: Use `--verbose` flag for detailed diagnostics
+
+.Subroutine debugging workflow example
+====
+[source,bash]
 ----
-$ fontisan ls FONT.{ttc,otc}
+# Convert with verbose output
+$ fontisan convert input.ttf --to otf --output output.otf --optimize --verbose
+
+# Validate the output
+$ fontisan validate output.otf
+
+# Check CharString structure
+$ fontisan info output.otf
 ----
 
-NOTE: In `extract_ttc`, this was done with `extract_ttc --list FONT.ttc`.
+If validation fails, try:
 
+[source,bash]
+----
+# Disable optimization
+$ fontisan convert input.ttf --to otf --output output.otf
 
-.List collection contents
+# Use stack-aware mode for safer optimization
+$ fontisan convert input.ttf --to otf --output output.otf --optimize --stack-aware
+----
+====
+
+.Optimization parameters
 [example]
 ====
-[source,shell]
+[source,bash]
 ----
-# List all fonts in a TTC with detailed info
-$ fontisan ls spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc
+# Adjust pattern matching sensitivity
+$ fontisan convert input.ttf --to otf --output output.otf \
+  --optimize \
+  --min-pattern-length 15 \
+  --max-subroutines 10000 \
+  --verbose
 
-Font 0: Noto Serif CJK JP
-  Family: Noto Serif CJK JP
-  Subfamily: Regular
-  PostScript: NotoSerifCJKJP-Regular
+# Disable ordering optimization
+$ fontisan convert input.ttf --to otf --output output.otf \
+  --optimize \
+  --no-optimize-ordering
+----
+====
 
-Font 1: Noto Serif CJK KR
-  Family: Noto Serif CJK KR
-  Subfamily: Regular
-  PostScript: NotoSerifCJKKR-Regular
+Where,
 
-Font 2: Noto Serif CJK SC
-  Family: Noto Serif CJK SC
-  Subfamily: Regular
-  PostScript: NotoSerifCJKSC-Regular
+`--optimize`:: Enable subroutine optimization (default: false)
+`--min-pattern-length N`:: Minimum pattern length in bytes (default: 10)
+`--max-subroutines N`:: Maximum number of subroutines to generate (default: 65,535)
+`--optimize-ordering`:: Optimize subroutine ordering by frequency (default: true)
+`--verbose`:: Show detailed optimization statistics
 
-Font 3: Noto Serif CJK TC
-  Family: Noto Serif CJK TC
-  Subfamily: Regular
-  PostScript: NotoSerifCJKTC-Regular
-----
-====
 
+=== Stack-aware optimization
 
-===== Show collection info
+==== General
 
-Show detailed information about a TrueType Collection (TTC), OpenType Collection
-(OTC), including the number of fonts and metadata for each font.
+Stack-aware optimization is an advanced mode that ensures all extracted patterns
+are stack-neutral, guaranteeing 100% safety and reliability.
 
-[source,shell]
-----
-$ fontisan info FONT.{ttc,otc}
-----
+Unlike normal byte-level pattern matching, stack-aware mode simulates CharString
+execution to track operand stack depth, only extracting patterns that maintain
+consistent stack state.
 
-NOTE: In `extract_ttc`, this was done with `extract_ttc --info FONT.ttc`.
+Key benefits:
 
-.Get collection information
-[example]
-====
-[source,shell]
-----
-# Detailed collection analysis
-$ fontisan info spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc --format yaml
+* **100% Reliability**: All patterns are validated to be stack-neutral
+* **No Stack Errors**: Eliminates stack underflow/overflow issues
+* **Faster Processing**: 6-12x faster than normal optimization due to early filtering
+* **Smaller Pattern Set**: Significantly fewer candidates reduce memory usage
 
----
-collection_type: ttc
-font_count: 4
-fonts:
-- index: 0
-  family_name: Noto Serif CJK JP
-  subfamily_name: Regular
-  postscript_name: NotoSerifCJKJP-Regular
-  font_format: opentype
-- index: 1
-  family_name: Noto Serif CJK KR
-  subfamily_name: Regular
-  postscript_name: NotoSerifCJKKR-Regular
-  font_format: opentype
-- index: 2
-  family_name: Noto Serif CJK SC
-  subfamily_name: Regular
-  postscript_name: NotoSerifCJKSC-Regular
-  font_format: opentype
-- index: 3
-  family_name: Noto Serif CJK TC
-  subfamily_name: Regular
-  postscript_name: NotoSerifCJKTC-Regular
-  font_format: opentype
-----
-====
+Trade-offs:
 
-===== Unpack fonts
+* **Lower Compression**: ~6% reduction vs ~11% with normal mode
+* **Fewer Patterns**: Filters out 90%+ of raw patterns for safety
+* **Stack Validation Overhead**: Adds stack tracking during analysis
 
-Extract all fonts from a TrueType Collection (TTC) or OpenType Collection (OTC)
-to a specified output directory.
+==== Command-line usage
 
-[source,shell]
-----
-$ fontisan unpack FONT.{ttc,otc} OUTPUT_DIR
+.Enable stack-aware optimization
+[example]
+====
+[source,bash]
 ----
+# Convert with stack-aware optimization
+$ fontisan convert input.ttf --to otf --output output.otf \
+  --optimize \
+  --stack-aware \
+  --verbose
 
-NOTE: In `extract_ttc`, this was done with `extract_ttc --unpack FONT.ttc OUTPUT_DIR`.
+Converting input.ttf to otf...
 
-===== Extract specific font
+Analyzing CharString patterns (4515 glyphs)...
+  Found 8566 potential patterns
+Selecting optimal patterns...
+  Selected 832 patterns for subroutinization
+Building subroutines...
+  Generated 832 subroutines
+Rewriting CharStrings with subroutine calls...
+  Rewrote 4515 CharStrings
 
-Extract a specific font from a TrueType Collection (TTC) or OpenType Collection (OTC) by its index.
+Subroutine Optimization Results:
+  Patterns found: 8566
+  Patterns selected: 832
+  Subroutines generated: 832
+  Estimated bytes saved: 46,280
+  CFF bias: 0
 
-[source,shell]
-----
-$ fontisan unpack FONT.{ttc,otc} --font-index INDEX OUTPUT.{ttf,otf}
+Conversion complete!
+  Input:  input.ttf (806.3 KB)
+  Output: output.otf (660.7 KB)
 ----
+====
 
-NOTE: In `extract_ttc`, this was done with `extract_ttc --font-index INDEX FONT.ttc OUTPUT.ttf`.
-
-.Extract with validation
+.Stack-aware vs normal mode
 [example]
 ====
-[source,shell]
+[source,bash]
 ----
-# Extract and validate simultaneously
-$ fontisan unpack spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc extracted_fonts/ --validate
+# Use the comparison script
+$ ruby scripts/compare_stack_aware.rb input.ttf
 
-Extracting font 0: Noto Serif CJK JP → extracted_fonts/NotoSerifCJKJP-Regular.ttf
-Extracting font 1: Noto Serif CJK KR → extracted_fonts/NotoSerifCJKKR-Regular.ttf
-Extracting font 2: Noto Serif CJK SC → extracted_fonts/NotoSerifCJKSC-Regular.ttf
-Extracting font 3: Noto Serif CJK TC → extracted_fonts/NotoSerifCJKTC-Regular.ttf
+File Size Reduction:
+  Normal: 81.49 KB (11.27%)
+  Stack-Aware: 43.17 KB (6.13%)
 
-Validation: All fonts extracted successfully
+Processing Times:
+  Normal: 18.38 s
+  Stack-Aware: 1.54 s (12x faster)
+
+Stack-Aware Efficiency: 52.97% of normal optimization
 ----
 ====
 
-===== Validate collection
+Where,
 
-Validate the structure and checksums of a TrueType Collection (TTC) or OpenType
-Collection (OTC).
+`--stack-aware`:: Enable stack-aware pattern detection (default: false)
 
-[source,shell]
-----
-$ fontisan validate FONT.{ttc,otc}
+==== Using the Ruby API
+
+.Basic stack-aware optimization
+[example]
+====
+[source,ruby]
 ----
+require 'fontisan'
 
-NOTE: In `extract_ttc`, this was done with `extract_ttc --validate FONT.ttc`.
+# Load TrueType font
+font = Fontisan::FontLoader.load('input.ttf')
 
+# Convert with stack-aware optimization
+converter = Fontisan::Converters::OutlineConverter.new
+tables = converter.convert(font, {
+  target_format: :otf,
+  optimize_subroutines: true,
+  stack_aware: true  # Enable safe mode
+})
 
-== Advanced features
+# Access optimization results
+optimization = tables.instance_variable_get(:@subroutine_optimization)
+puts "Patterns found: #{optimization[:pattern_count]}"
+puts "Stack-neutral patterns: #{optimization[:selected_count]}"
+puts "Processing time: #{optimization[:processing_time]}s"
 
-Fontisan provides capabilities:
+# Write output
+Fontisan::FontWriter.write_to_file(
+  tables,
+  'output.otf',
+  sfnt_version: 0x4F54544F
+)
+----
+====
 
-.Font analysis and inspection
-* Extract OpenType tables with checksums and offsets
-* Display Unicode mappings and glyph names
-* Analyze variable font axes and instances
-* Show supported scripts and OpenType features
-* Dump raw binary table data
+==== Technical details
 
-.Format conversion and subsetting
-* Convert between TTF, OTF, WOFF, and WOFF2 formats
-* Create font subsets with specific glyph ranges
-* Validate font structure and integrity
-* Generate SVG representations of glyphs
+Stack-aware mode uses a three-stage validation process:
 
-.Collection creation
-* Build new TTC files from individual fonts
-* Optimize collection with table deduplication
-* Pack fonts with shared tables for smaller file sizes
+[source]
+----
+CharString Bytes → Stack Tracking → Pattern Validation → Safe Patterns
+    (Input)         (Simulate)       (Filter)           (Output)
+----
 
-For complete migration guide, see link:docs/EXTRACT_TTC_MIGRATION.md[extract_ttc Migration Guide].
+**Stack tracking**:
 
-=== CLI Examples for Advanced Features
+. Simulates CharString execution without full interpretation
+. Records stack depth at each byte position
+. Handles 40+ Type 2 CharString operators with correct stack effects
 
-==== Collection Creation and Management
+**Pattern validation**:
 
-.Create TTC collection from multiple fonts
-[source,shell]
-----
-# Pack fonts into TTC with table sharing optimization
-$ fontisan pack font1.ttf font2.ttf font3.ttf --output family.ttc --analyze
+. Checks if pattern start and end have same stack depth
+. Ensures no stack underflow during pattern execution
+. Verifies consistent results regardless of initial stack state
 
-Collection Analysis:
-Total fonts: 3
-Shared tables: 12
-Potential space savings: 45.2 KB
-Table sharing: 68.5%
+**Stack-neutral pattern** criteria. Pattern is stack-neutral if:
 
-Collection created successfully:
-  Output: family.ttc
-  Format: TTC
-  Fonts: 3
-  Size: 245.8 KB
-  Space saved: 45.2 KB
-  Sharing: 68.5%
+. depth_at(pattern_start) == depth_at(pattern_end)
+. No negative depth during pattern execution
+. Pattern produces same result for any valid initial stack
++
+.Example Stack-Neutral Pattern
+[source]
 ----
-
-.Create OTC collection from OpenType fonts
-[source,shell]
+10 20 rmoveto  # Pushes 2 operands, consumes 2 → neutral
 ----
-$ fontisan pack Regular.otf Bold.otf Italic.otf --output family.otc --format otc
++
+.Example Non-Neutral Pattern
+[source]
 ----
-
-.Extract fonts from collection
-[source,shell]
+10 20 add  # Pushes 2, consumes 2, produces 1 → NOT neutral
 ----
-# Extract all fonts from collection
-$ fontisan unpack family.ttc --output-dir extracted/
 
-Collection unpacked successfully:
-  Input: family.ttc
-  Output directory: extracted/
-  Fonts extracted: 3/3
-  - font1.ttf (89.2 KB)
-  - font2.ttf (89.2 KB)
-  - font3.ttf (67.4 KB)
+==== When to use stack-aware mode
 
-# Extract specific font with format conversion
-$ fontisan unpack family.ttc --output-dir extracted/ --font-index 0 --format woff2
-----
+**Recommended for**:
 
-==== Format Conversion
+* Production font conversion where reliability is critical
+* Fonts that will undergo further processing
+* Web fonts where correctness matters more than minimal size
+* Situations where testing/validation is limited
 
-.Convert TTF to WOFF2 for web usage
-[source,shell]
-----
-$ fontisan convert font.ttf --to woff2 --output font.woff2
+**Normal mode acceptable for**:
 
-Converting font.ttf to woff2...
-Conversion complete!
-  Input:  font.ttf (245.8 KB)
-  Output: font.woff2 (89.2 KB)
-----
+* Development/testing environments
+* When full validation will be performed post-conversion
+* Maximum compression is priority over guaranteed safety
 
-.Convert to SVG format
-[source,shell]
-----
-$ fontisan convert font.ttf --to svg --output font.svg
+==== Using the Ruby API
 
-Converting font.ttf to svg...
-Conversion complete!
-  Input:  font.ttf (245.8 KB)
-  Output: font.svg (1.2 MB)
+.Basic optimization
+[example]
+====
+[source,ruby]
 ----
+require 'fontisan'
 
-==== Font Subsetting
+# Load TrueType font
+font = Fontisan::FontLoader.load('input.ttf')
 
-.Create PDF-optimized subset
-[source,shell]
-----
-$ fontisan subset font.ttf --text "Hello World" --output subset.ttf --profile pdf
+# Convert with optimization
+converter = Fontisan::Converters::OutlineConverter.new
+tables = converter.convert(font, {
+  target_format: :otf,
+  optimize_subroutines: true
+})
 
-Subset font created:
-  Input: font.ttf
-  Output: subset.ttf
-  Original glyphs: 1253
-  Subset glyphs: 12
-  Profile: pdf
-  Size: 12.4 KB
-----
+# Access optimization results
+optimization = tables.instance_variable_get(:@subroutine_optimization)
+puts "Patterns found: #{optimization[:pattern_count]}"
+puts "Selected: #{optimization[:selected_count]}"
+puts "Savings: #{optimization[:savings]} bytes"
 
-.Subset with Unicode ranges
-[source,shell]
-----
-$ fontisan subset font.ttf --unicode "U+0041-U+005A,U+0061-U+007A" --output latin.ttf
+# Write output
+Fontisan::FontWriter.write_to_file(
+  tables,
+  'output.otf',
+  sfnt_version: 0x4F54544F
+)
 ----
+====
 
-==== Font Validation
-
-.Validate font with different levels
-[source,shell]
+.Custom optimization parameters
+[example]
+====
+[source,ruby]
 ----
-# Standard validation (allows warnings)
-$ fontisan validate font.ttf
+require 'fontisan'
 
-# Strict validation (no warnings allowed)
-$ fontisan validate font.ttf --level strict
+font = Fontisan::FontLoader.load('input.ttf')
+converter = Fontisan::Converters::OutlineConverter.new
+
+# Fine-tune optimization
+tables = converter.convert(font, {
+  target_format: :otf,
+  optimize_subroutines: true,
+  min_pattern_length: 15,
+  max_subroutines: 5000,
+  optimize_ordering: true,
+  verbose: true
+})
 
-# Detailed validation report
-$ fontisan validate font.ttf --format yaml
+# Analyze results
+optimization = tables.instance_variable_get(:@subroutine_optimization)
+if optimization[:selected_count] > 0
+  efficiency = optimization[:savings].to_f / optimization[:selected_count]
+  puts "Average savings per subroutine: #{efficiency.round(2)} bytes"
+end
 ----
+====
 
-==== Variable Font Instances
 
-.Generate static instance from variable font
-[source,shell]
-----
-# Create bold instance
-$ fontisan instance variable.ttf --wght=700 --output bold.ttf
+== Round-Trip validation
 
-# Use named instance
-$ fontisan instance variable.ttf --named-instance="Bold" --output bold.ttf
+=== General
 
-# List available instances
-$ fontisan instance variable.ttf --list-instances
-----
+Fontisan ensures high-fidelity font conversion through comprehensive round-trip
+validation.
 
-==== Advanced Font Analysis
+When converting between TrueType (TTF) and OpenType/CFF (OTF) formats, the
+validation system verifies that glyph geometry is preserved accurately.
 
-.Dump raw table data for analysis
-[source,shell]
-----
-$ fontisan dump-table font.ttf name > name_table.bin
-$ fontisan dump-table font.ttf GPOS > gpos_table.bin
-----
+Key validation features:
 
-.Analyze font structure
-[source,shell]
-----
-# List all OpenType tables with details
-$ fontisan tables font.ttf --format yaml
+* **Command-Level Precision**: Validates individual drawing commands (move, line, curve)
+* **Coordinate Tolerance**: Accepts ±2 pixels tolerance for rounding during conversion
+* **Format-Aware Comparison**: Handles differences between TrueType quadratic and CFF cubic curves
+* **Closepath Handling**: Smart detection of geometrically closed vs open contours
 
-# Show variable font information
-$ fontisan variable font.ttf
+=== Technical details
 
-# Display optical size information
-$ fontisan optical-size font.ttf
-----
+Round-trip validation works by:
 
-.Get comprehensive font information
-[source,shell]
+[source]
+----
+Original TTF → Convert to CFF → Extract CFF → Compare Geometry
+    (Input)      (Encode)         (Decode)      (Validate)
 ----
-# Basic font info
-$ fontisan info font.ttf
 
-# Scripts and features analysis
-$ fontisan scripts font.ttf
-$ fontisan features font.ttf --script latn
+**Validation process**:
+
+. Extract glyph outlines from original TTF
+. Convert to CFF format with CharString encoding
+. Parse CFF CharStrings back to universal outlines
+. Compare geometry with coordinate tolerance (±2 pixels)
 
-# Unicode coverage
-$ fontisan unicode font.ttf
+**Format differences handled**:
 
-# Glyph names
-$ fontisan glyphs font.ttf
-----
+* **Closepath**: CFF has implicit closepath, TTF has explicit
+* **Curve types**: TrueType quadratic (`:quad_to`) vs CFF cubic (`:curve_to`)
+* **Coordinate rounding**: Different number encoding causes minor differences
 
+**Validation criteria**: Geometry Match:
+. Same bounding box (±2 pixel tolerance)
+. Same number of path commands (excluding closepath)
+. Same endpoint coordinates for curves (±2 pixels)
+. Quadratic→cubic conversion accepted
 
 
-== Universial Outline Model
+== Universal outline model
 
 === General
 
-Universal Outline Model (UOM) is based on a self-stable algorithm for converting
-soft glyph contours to outline format used in all tools of Fontisan. This
-ability allows easy modeling of import glyphs from one font format
-TrueType (TTF, OTF binaries), converting glyph elements into any font
+The Fontisan Universal Outline Model (UOM) is based on a self-stable algorithm
+for converting soft glyph contours to outline format used in all tools of
+Fontisan. This ability allows easy modeling of import glyphs from one font
+format TrueType (TTF, OTF binaries), converting glyph elements into any font
 format, TrueType for example.
 
 === Locker
 
-Locker is the new object-oriented model for storing imported outlines and
-glyphs. Storage is based on monotonic spirals computed based on 2D points and
-curves. Invisible converting from TrueType, CFF Opentype and ColorGlyph formats.
+Locker is an object-oriented model for storing imported outlines and glyphs.
+Storage is based on monotonic spirals computed based on 2D points and curves.
+Invisible converting from TrueType, CFF Opentype and ColorGlyph formats.
 
 === Translator
 
-Translation from and to PostScript custom CFF charset. New encoding/decoding
-includes PostScript type2/3/composite Loron.
+Translation is an object-oriented model for converting from and to PostScript
+custom CFF charset. New encoding/decoding includes PostScript Type 2/3/composite
+Loron.
 
 === ColorGlyph
 
@@ -1963,10 +2165,10 @@ combined with TrueType outlines.
 
 === Universal fonts
 
-Fontisan can now:
+Fontisan can:
 
 * Import TrueType contours into Universal Outline Model (UOM)
-* Operate UOM outlines including transformations, serialization (save),
+* Operate UOM outlines including transformations, serialization (save)
 * Select and convert all UOM contours to TTF/OTF
 * Cleaning
 * Improve
@@ -1978,26 +2180,26 @@ Fontisan can now:
 
 === Universal glyphs
 
-Fontisan can now:
+Fontisan can:
 
-* Use Universal Outline Model (UOM) for TrueType contours and CFF color glyphs,
-* Repository for investor-defined fonts,
-* Custom Unicode assignments, rewriting Unicode configurations,
+* Use Universal Outline Model (UOM) for TrueType contours and CFF color glyphs
+* Repository for investor-defined fonts
+* Custom Unicode assignments, rewriting Unicode configurations
 * Saving and import outlines, including TrueType and OTF/CFF
 * Rendering for advanced font types
 * Universal layer stacking for advanced color glyph combinations
 
 === Universal color layers
 
-(Converted TT, OTF files)
+(Converted TTF, OTF files)
 
-Fontisan can now:
+Fontisan can:
 
-* Import embedded TTF/OTF color layers,
-* Assembler from individual TTF/OTF slices,
-* Advanced managing layer maps in TTF color (CFF) fonts,
-* Advenced color layer blending style management,
-* Managing Gray/Overprint/Color-Full image comps and layer convertion
+* Import embedded TTF/OTF color layers
+* Assembler from individual TTF/OTF slices
+* Advanced managing layer maps in TTF color (CFF) fonts
+* Advanced color layer blending style management
+* Managing Gray/Overprint/Color-Full image comps and layer conversion
 * Strategy management for smart vector combos from raster
 * Importing and generation PNG block ruler layers