fontisan 0.2.1 → 0.2.3

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
@@ -85,2027 +86,2105 @@ 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)
-* Hint preservation during TTF ↔ OTF conversion (optional, partially complete)
+* 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 (~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/loca 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
+[source,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
+----
+====
 
-Font integrity validation is now enabled by default for all conversions.
-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:
+== List glyph names
 
-[source,bash]
-----
-fontisan validate output.otf
-fontisan info output.otf
-fontisan tables output.otf
-----
+=== General
+
+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.
 
-=== Using the Ruby API
+=== Command-line usage
 
-==== Basic conversion
+Syntax:
 
-[source,ruby]
+[source,shell]
+----
+$ fontisan glyphs FONT_FILE [--format FORMAT]
 ----
-require 'fontisan'
 
-# Load a TrueType font
-font = Fontisan::FontLoader.load('input.ttf')
+Where,
 
-# Convert to OpenType/CFF
-converter = Fontisan::Converters::OutlineConverter.new
-tables = converter.convert(font, target_format: :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  # 'OTTO' for OpenType/CFF
-)
+
+.List of glyph names in Libertinus Serif Regular
+[example]
+====
+[source,shell]
+----
+$ fontisan glyphs spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
 ----
 
-==== Using FormatConverter
+[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
+     ...
 ----
-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)
+== Show Unicode mappings
 
-  # Write output
-  Fontisan::FontWriter.write_to_file(
-    tables,
-    'output.otf',
-    sfnt_version: 0x4F54544F
-  )
-end
-----
+=== General
 
-==== Check supported conversions
+Display Unicode codepoint to glyph index mappings from the cmap table. Shows
+which glyphs are assigned to which Unicode characters.
 
-[source,ruby]
-----
-converter = Fontisan::Converters::FormatConverter.new
+=== Command-line usage
+Syntax:
 
-# Check if conversion is supported
-converter.supported?(:ttf, :otf)  # => true
-converter.supported?(:otf, :ttf)  # => true
+[source,shell]
+----
+$ fontisan unicode FONT_FILE [--format FORMAT]
+----
 
-# Get all supported conversions
-converter.all_conversions
-# => [{from: :ttf, to: :otf}, {from: :otf, to: :ttf}, ...]
+Where,
 
-# Get supported targets for a source format
-converter.supported_targets(:ttf)
-# => [:ttf, :otf, :woff2, :svg]
-----
+`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
 
-=== Technical Details
 
-The converter uses a three-stage pipeline:
+.Unicode to glyph mappings in Libertinus Serif Regular
+[example]
+====
+[source,shell]
+----
+$ fontisan unicode spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
+----
 
-[source]
+[source,text]
 ----
-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
+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
+...
 ----
+====
 
-==== 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
+== Variable font information
 
-==== OTF → TTF conversion
+=== General
 
-. 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
+Display variation axes and named instances for variable fonts. Shows the design
+space and predefined styles available in the font.
 
-==== Curve conversion
+=== Command-line usage
 
-**Quadratic to cubic** (lossless):
+Syntax:
 
-[source]
+[source,shell]
+----
+$ fontisan variable FONT_FILE [--format FORMAT]
 ----
-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)
+Where,
 
-Result: Exact mathematical equivalent
-----
+`FONT_FILE`:: Path to the variable font file
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
 
-**Cubic to quadratic** (adaptive):
 
-[source]
+.Variable font axes and instances in Mona Sans
+[example]
+====
+[source,shell]
+----
+$ fontisan variable spec/fixtures/fonts/MonaSans/variable/MonaSans[wdth,wght].ttf
 ----
-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
 
-Result: High-quality approximation with < 0.5 unit deviation
+[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
+...
 ----
+====
 
-=== Compound Glyph Support
 
-Fontisan fully supports compound (composite) glyphs in both conversion directions:
+== Generate static instances from variable fonts
 
-* **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
+Generate static font instances from variable fonts at specific variation
+coordinates and output in any supported format (TTF, OTF, WOFF).
 
-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 instance VARIABLE_FONT [OPTIONS]
+----
 
-==== Technical Implementation
+Where,
 
-Compound glyphs reference other glyphs by index and apply 2×3 affine transformation matrices:
+`VARIABLE_FONT`:: Path to the variable font file
+`OPTIONS`:: Instance generation options
 
-[source]
-----
-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)
-----
-
-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)
+Options:
 
-=== Subroutine Optimization
+`--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
 
-==== General
 
-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.
+.Generate bold instance at wght=700
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --wght 700 --output bold.ttf
 
-Key features:
+Generating instance... done
+Writing output... done
+Static font instance written to: bold.ttf
+----
+====
 
-* **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
+.Generate instance and convert to OTF
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --wght 300 --to otf --output light.otf
 
-Typical space savings: 30-50% reduction in CFF table size for fonts with similar glyph shapes.
+Generating instance... done
+Writing output... done
+Static font instance written to: light.otf
+----
+====
 
-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.
+.Generate instance and convert to WOFF
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --wght 600 --to woff --output semibold.woff
 
-==== Subroutine Optimization Improvements (v2.0.0-rc1)
+Generating instance... done
+Writing output... done
+Static font instance written to: semibold.woff
+----
+====
 
-===== Bug Fixes
+.Generate instance with multiple axes
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --wght 600 --wdth 75 --output condensed.ttf
 
-Three critical bugs were fixed in v2.0.0-rc1 to improve CharString parsing and round-trip validation:
+Generating instance... done
+Writing output... done
+Static font instance written to: condensed.ttf
+----
+====
 
-. **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
+.List available named instances
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --list-instances
 
-. **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
+Available named instances:
 
-. **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
+  [0] Instance 4
+    Coordinates:
+      wdth: 75.0
+      wght: 200.0
 
-These fixes significantly reduce parsing errors after optimization (from 91 failures to ~140 warnings in integration tests).
+  [1] Instance 5
+    Coordinates:
+      wdth: 75.0
+      wght: 250.0
 
-===== Edge Cases
+  [2] Instance 6
+    Coordinates:
+      wdth: 75.0
+      wght: 300.0
+----
+====
 
-The optimizer now correctly handles:
+.Use named instance
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --named-instance 0 --output thin.ttf
+----
+====
 
-* **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
+.Preview instance generation (dry-run)
+[example]
+====
+[source,shell]
+----
+$ fontisan instance variable.ttf --wght 700 --dry-run
 
-===== Troubleshooting
+Dry-run mode: Preview of instance generation
 
-If you encounter CharString parsing errors after optimization:
+Coordinates:
+  wght: 700.0
 
-. **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
+Output would be written to: variable-instance.ttf
+Output
 
-Example debugging workflow:
+ format: same as input
 
-[source,bash]
+Use without --dry-run to actually generate the instance.
 ----
-# 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
-----
+== Optical size information
 
-If validation fails, try:
+=== General
 
-[source,bash]
-----
-# Disable optimization
-$ fontisan convert input.ttf --to otf --output output.otf
+Display optical size range from the OS/2 table for fonts designed for specific
+point sizes.
 
-# Use stack-aware mode for safer optimization
-$ fontisan convert input.ttf --to otf --output output.otf --optimize --stack-aware
-----
+=== Command-line usage
 
-==== Using the CLI
+Syntax:
 
-.Convert with subroutine optimization
-[example]
-====
-[source,bash]
+[source,shell]
+----
+$ fontisan optical-size FONT_FILE [--format FORMAT]
 ----
-# Enable optimization with default settings
-$ fontisan convert input.ttf --to otf --output output.otf --optimize --verbose
 
-Converting input.ttf to otf...
+Where,
 
-=== Subroutine Optimization Results ===
-  Patterns found: 234
-  Patterns selected: 89
-  Subroutines generated: 89
-  Estimated bytes saved: 45,234
-  CFF bias: 107
+`FONT_FILE`:: Path to the font file with optical sizing
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
 
-Conversion complete!
-  Input:  input.ttf (806.3 KB)
-  Output: output.otf (979.5 KB)
-----
-====
 
-.SQLite optimization parameters
+.Optical size information in Libertinus Serif Display
 [example]
 ====
-[source,bash]
+[source,shell]
+----
+$ fontisan optical-size spec/fixtures/fonts/libertinus/ttf/LibertinusSerifDisplay-Regular.ttf
 ----
-# Adjust pattern matching sensitivity
-$ fontisan convert input.ttf --to otf --output output.otf \
-  --optimize \
-  --min-pattern-length 15 \
-  --max-subroutines 10000 \
-  --verbose
 
-# Disable ordering optimization
-$ fontisan convert input.ttf --to otf --output output.otf \
-  --optimize \
-  --no-optimize-ordering
+[source,text]
+----
+Size range: [18, 72) pt  (source: OS/2_usLowerOpticalPointSize)
 ----
 ====
 
-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
+== List supported scripts
 
-==== Stack-Aware Optimization
+=== General
 
-===== General
+Show all scripts (writing systems) supported by the font, extracted from GSUB
+and GPOS tables. Useful for understanding language coverage.
 
-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.
+=== Command-line usage
 
-Key benefits:
+Syntax:
 
-* **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
+[source,shell]
+----
+$ fontisan scripts FONT_FILE [--format FORMAT]
+----
 
-Trade-offs:
+Where,
 
-* **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
+`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
+`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
 
-===== Using the CLI
 
-.Enable stack-aware optimization
+.Supported scripts in Libertinus Serif Regular
 [example]
 ====
-[source,bash]
+[source,shell]
+----
+$ fontisan scripts spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
 ----
-# Convert with stack-aware optimization
-$ fontisan convert input.ttf --to otf --output output.otf \
-  --optimize \
-  --stack-aware \
-  --verbose
-
-Converting input.ttf to otf...
-
-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
 
-Subroutine Optimization Results:
-  Patterns found: 8566
-  Patterns selected: 832
-  Subroutines generated: 832
-  Estimated bytes saved: 46,280
-  CFF bias: 0
+[source,text]
+----
+Script count: 5
 
-Conversion complete!
-  Input:  input.ttf (806.3 KB)
-  Output: output.otf (660.7 KB)
+DFLT  Default
+cyrl  Cyrillic
+grek  Greek
+hebr  Hebrew
+latn  Latin
 ----
 ====
 
-.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%)
+== List OpenType features
 
-Processing Times:
-  Normal: 18.38 s
-  Stack-Aware: 1.54 s (12x faster)
+=== General
 
-Stack-Aware Efficiency: 52.97% of normal optimization
-----
-====
+Show OpenType layout features (typography features like ligatures, kerning,
+small capitals) available for specific scripts or all scripts.
 
-Where,
+=== Command-line usage
 
-`--stack-aware`:: Enable stack-aware pattern detection (default: false)
+Syntax:
 
-===== Using the Ruby API
+[source,shell]
+----
+$ fontisan features FONT_FILE [--script SCRIPT] [--format FORMAT]
+----
 
-.Basic stack-aware 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 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"
+[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
 ----
 ====
 
-===== Technical Details
-
-Stack-aware mode uses a three-stage validation process:
 
-[source]
+.OpenType features for all scripts
+[example]
+====
+[source,shell]
 ----
-CharString Bytes → Stack Tracking → Pattern Validation → Safe Patterns
-    (Input)         (Simulate)       (Filter)           (Output)
+$ fontisan features spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
 ----
 
-**Stack Tracking**:
+[source,text]
+----
+Script: DFLT
+Feature count: 4
 
-. Simulates CharString execution without full interpretation
-. Records stack depth at each byte position
-. Handles 40+ Type 2 CharString operators with correct stack effects
+  cpsp  Capital Spacing
+  kern  Kerning
+  mark  Mark Positioning
+  mkmk  Mark to Mark Positioning
 
-**Pattern Validation**:
+Script: cyrl
+Feature count: 4
 
-. 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
+  cpsp  Capital Spacing
+  kern  Kerning
+  mark  Mark Positioning
+  mkmk  Mark to Mark Positioning
 
-**Stack-Neutral Pattern** criteria:
+Script: grek
+Feature count: 4
 
-[source]
-----
-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
-----
+  cpsp  Capital Spacing
+  kern  Kerning
+  mark  Mark Positioning
+  mkmk  Mark to Mark Positioning
 
-**Example Stack-Neutral Pattern**:
-[source]
-----
-10 20 rmoveto  # Pushes 2 operands, consumes 2 → neutral
-----
+Script: hebr
+Feature count: 2
 
-**Example Non-Neutral Pattern**:
-[source]
-----
-10 20 add  # Pushes 2, consumes 2
+  mark  Mark Positioning
+  mkmk  Mark to Mark Positioning
 
-, produces 1 → NOT neutral
+Script: latn
+Feature count: 4
+
+  cpsp  Capital Spacing
+  kern  Kerning
+  mark  Mark Positioning
+  mkmk  Mark to Mark Positioning
 ----
+====
 
-===== When to Use Stack-Aware Mode
 
-**Recommended for**:
+== Dump raw table data
 
-* 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
+=== General
 
-**Normal mode acceptable for**:
+Extract raw binary data from a specific OpenType table. Useful for detailed
+analysis or debugging font issues.
 
-* Development/testing environments
-* When full validation will be performed post-conversion
-* Maximum compression is priority over guaranteed safety
+=== Command-line usage
 
-==== Using the Ruby API
+TODO: should support output to file directly with `--output FILE`.
 
-.Basic optimization
+Syntax:
+
+[source,shell]
+----
+$ fontisan dump-table FONT_FILE TABLE_TAG
+----
+
+Where,
+
+`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
+`TABLE_TAG`:: Four-character table tag (e.g., `name`, `head`, `GSUB`, `GPOS`)
+
+
+.Dump raw table data to files
 [example]
 ====
-[source,ruby]
+[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
 ----
-require 'fontisan'
 
-# Load TrueType font
-font = Fontisan::FontLoader.load('input.ttf')
+The output is binary data written directly to stdout, which can be redirected to
+a file for further analysis.
+====
 
-# 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"
+== Export font structure
 
-# Write output
-Fontisan::FontWriter.write_to_file(
-  tables,
-  'output.otf',
-  sfnt_version: 0x4F54544F
-)
+=== General
+
+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.
+
+=== Command-line usage
+
+Syntax:
+
+[source,shell]
+----
+$ fontisan export FONT_FILE [--output FILE] [--format FORMAT] [--tables TABLES] [--binary-format FORMAT]
 ----
-====
 
-.Custom optimization parameters
+Where,
+
+`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`
+
+
+.Export font to YAML format
 [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
-})
+$ fontisan export spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --output font.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
+# Output: font.yaml with complete font structure in YAML
 ----
 ====
 
-==== Technical Details
+.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
+----
 
-The subroutine optimizer uses a four-stage pipeline:
+Exports only the specified tables in FontTools TTX XML format for compatibility
+with fonttools.
+====
 
-[source]
+.Export to JSON with base64 binary encoding
+[example]
+====
+[source,shell]
 ----
-CharStrings → Pattern Analysis → Selection → Ordering → Metadata
-  (Input)      (Find repeats)    (Optimize)  (Frequency)  (Output)
+$ fontisan export font.ttf --format json --binary-format base64 --output font.json
 ----
 
-**Pattern Analysis**:
-
-. Extracts byte sequences from all CharStrings
-. Identifies repeating patterns across glyphs
-. Filters by minimum pattern length (default: 10 bytes)
-. Builds pattern frequency map
+Uses base64 encoding for binary data instead of hexadecimal, useful for
+JSON-based workflows.
+====
 
-**Selection Algorithm**:
 
-. 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
+== Version information
 
-**Ordering Optimization**:
+=== General
 
-. 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**:
+=== Command-line usage
 
-[source]
+[source,shell]
 ----
-Subroutine count    CFF Bias
------------------   ---------
-0-1239              107
-1240-33899          1131
-33900-65535         32768
+fontisan version
 ----
 
-The bias value determines how subroutine indices are encoded in CharStrings, affecting the final size.
 
-=== Round-Trip Validation
+== Font collections
 
-==== General
+=== General
 
-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.
+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.
 
-Key validation features:
+Both TTC and OTC files use the same `ttcf` tag in their binary format, but
+differ in the type of font data they contain:
 
-* **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
+TTC (TrueType Collection):: Supported since OpenType 1.4. Contains fonts with
+TrueType outlines (glyf table). Multiple fonts can share identical tables for
+efficient storage. File extension: `.ttc`
 
-==== Technical Details
+OTC (OpenType Collection):: Supported since OpenType 1.8. Contains fonts with
+CFF-format outlines (CFF table). Provides the same storage benefits and
+glyph-count advantages as TTC but for CFF fonts. File extension: `.otc`
 
-Round-trip validation works by:
+The collection format allows:
 
-[source]
-----
-Original TTF → Convert to CFF → Extract CFF → Compare Geometry
-    (Input)      (Encode)         (Decode)      (Validate)
-----
-
-**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**:
-
-* **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**:
-
-[source]
-----
-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
-----
+Table sharing::
+Identical tables are stored once and referenced by multiple fonts
 
-==== Test Coverage
+Gap mode::
+Overcomes the 65,535 glyph limit per font by distributing glyphs across multiple
+fonts in a single file
 
-The validation suite tests:
+Efficient storage::
+Significant size reduction, especially for CJK fonts (e.g., Noto CJK OTC is ~10
+MB smaller than separate OTF files)
 
-* **Without Optimization**: All glyphs convert correctly ✅
-* **With Optimization**: Pending fix for subroutine bug (91 glyphs affected)
+Fontist returns the appropriate collection type based on the font data:
 
-**Status**:
-```
-Round-trip validation: 100% passing (without optimization)
-Test suite: 2870/2870 passing, 15 pending (future features)
-```
+* Examines font data within collection to determine type (TTC vs OTC)
+* TTC contains fonts with TrueType outlines (glyf table)
+* OTC contains fonts with CFF outlines (CFF table)
+* If ANY font in the collection has CFF outlines, use OpenTypeCollection
+* Only use TrueTypeCollection if ALL fonts have TrueType outlines
 
-==== Known Issues
+=== List fonts
 
-**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.
+==== General
 
-=== Current Limitations
+List all fonts in a TrueType Collection (TTC) or OpenType Collection (OTC), with
+their index, family name, and style.
 
-==== Features not yet implemented
+==== Command-line usage
 
-* **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
+[source,shell]
+----
+$ fontisan ls FONT.{ttc,otc}
+----
 
-==== Optimization Preview Mode
+NOTE: In `extract_ttc`, this was done with `extract_ttc --list FONT.ttc`.
 
-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
+.List collection contents
+[example]
+====
+[source,shell]
+----
+# List all fonts in a TTC with detailed info
+$ fontisan ls spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc
 
-=== Planned Features
+Font 0: Noto Serif CJK JP
+  Family: Noto Serif CJK JP
+  Subfamily: Regular
+  PostScript: NotoSerifCJKJP-Regular
 
-==== Phase 2 (Current development phase)
+Font 1: Noto Serif CJK KR
+  Family: Noto Serif CJK KR
+  Subfamily: Regular
+  PostScript: NotoSerifCJKKR-Regular
 
-* CFF table serialization with subroutine support (in progress)
-* Hint preservation and conversion
-* CFF2 support for variable fonts
-* Round-trip conversion validation
-* Batch conversion support
+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
+----
+====
 
-== Usage
 
-=== Command-line interface
+=== Show collection info
 
-==== Font information
+==== General
 
-Extract comprehensive metadata from font files. This includes font names,
-version information, designer credits, vendor details, licensing information,
-and font metrics.
+Show detailed information about a TrueType Collection (TTC) or OpenType Collection
+(OTC), including the number of fonts and metadata for each font.
 
-Syntax:
+==== Command-line usage
 
 [source,shell]
 ----
-$ fontisan info FONT_FILE [--format FORMAT]
+$ fontisan info FONT.{ttc,otc}
 ----
 
-Where,
-
-`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
-
+NOTE: In `extract_ttc`, this was done with `extract_ttc --info FONT.ttc`.
 
-.Font information for Libertinus Serif Regular
+.Get collection information
 [example]
 ====
 [source,shell]
 ----
-$ fontisan info spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
+# Detailed collection analysis
+$ fontisan info spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc --format 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
+---
+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
 ----
 ====
 
 
-.Output in structured YAML format
-[example]
-====
+=== 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 info spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --format yaml
+$ fontisan unpack FONT.{ttc,otc} OUTPUT_DIR
 ----
 
-[source,yaml]
+NOTE: In `extract_ttc`, this was done with `extract_ttc --unpack FONT.ttc OUTPUT_DIR`.
+
+.Extract fonts from collection
+[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
+# 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)
+
+# Extract specific font with format conversion
+$ fontisan unpack family.ttc --output-dir extracted/ --font-index 0 --format woff2
 ----
 ====
 
+=== Extract specific font
 
-==== List OpenType tables
+==== General
 
-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.
+Extract a specific font from a TrueType Collection (TTC) or OpenType Collection
+(OTC) by its index.
 
-Syntax:
+==== Command-line usage
 
 [source,shell]
 ----
-$ fontisan tables FONT_FILE [--format FORMAT]
+$ fontisan unpack FONT.{ttc,otc} --font-index INDEX OUTPUT.{ttf,otf}
 ----
 
-Where,
-
-`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+NOTE: In `extract_ttc`, this was done with `extract_ttc --font-index INDEX FONT.ttc OUTPUT.ttf`.
 
-.List of OpenType tables in Libertinus Serif Regular
+.Extract with validation
 [example]
 ====
 [source,shell]
 ----
-$ fontisan tables spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
-----
+# Extract and validate simultaneously
+$ fontisan unpack spec/fixtures/fonts/NotoSerifCJK/NotoSerifCJK.ttc extracted_fonts/ --validate
 
-[source,text]
-----
-SFNT Version: TrueType (0x00010000)
-Number of tables: 16
+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
 
-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)
+Validation: All fonts extracted successfully
 ----
 ====
 
-.Output in structured YAML format
-[example]
-====
-[source,shell]
-----
-$ fontisan tables spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf --format yaml
-----
+=== Pack fonts into collection
 
-[source,yaml]
+==== General
+
+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]
 ----
----
-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
+# Pack fonts into TTC with table sharing optimization
+$ fontisan pack font1.ttf font2.ttf font3.ttf --output family.ttc --analyze
 
-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.
+Collection Analysis:
+Total fonts: 3
+Shared tables: 12
+Potential space savings: 45.2 KB
+Table sharing: 68.5%
 
-Syntax:
+Collection created successfully:
+  Output: family.ttc
+  Format: TTC
+  Fonts: 3
+  Size: 245.8 KB
+  Space saved: 45.2 KB
+  Sharing: 68.5%
+----
 
+.Create OTC collection from OpenType fonts
 [source,shell]
 ----
-$ fontisan glyphs FONT_FILE [--format FORMAT]
+$ fontisan pack Regular.otf Bold.otf Italic.otf --output family.otc --format otc
 ----
 
-Where,
 
-`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
 
-.List of glyph names in Libertinus Serif Regular
-[example]
-====
 [source,shell]
 ----
-$ fontisan glyphs spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
+$ fontisan validate FONT.{ttc,otc}
 ----
 
-[source,text]
-----
-Glyph count: 2731
-Source: post_2.0
+NOTE: In `extract_ttc`, this was done with `extract_ttc --validate FONT.ttc`.
 
-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
-     ...
-----
-====
 
-==== Show Unicode mappings
+== Advanced features
 
-Display Unicode codepoint to glyph index mappings from the cmap table. Shows
-which glyphs are assigned to which Unicode characters.
+Fontisan provides capabilities:
 
-Syntax:
+.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
 
-[source,shell]
-----
-$ fontisan unicode FONT_FILE [--format FORMAT]
-----
+.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
 
-Where,
+.Collection creation
+* Build new TTC files from individual fonts
+* Optimize collection with table deduplication
+* Pack fonts with shared tables for smaller file sizes
 
-`FONT_FILE`:: Path to the font file (OTF, TTF, or TTC)
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+For complete migration guide, see link:docs/EXTRACT_TTC_MIGRATION.md[extract_ttc Migration Guide].
 
 
-.Unicode to glyph mappings in Libertinus Serif Regular
-[example]
-====
-[source,shell]
-----
-$ fontisan unicode spec/fixtures/fonts/libertinus/ttf/LibertinusSerif-Regular.ttf
-----
 
-[source,text]
-----
-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
-...
-----
-====
+== Loading modes
 
-==== Variable font information
+=== General
 
-Display variation axes and named instances for variable fonts. Shows the design
-space and predefined styles available in the font.
+Fontisan provides a flexible loading modes architecture that enables efficient
+font parsing for different use cases.
 
-Syntax:
+The system supports two distinct modes:
 
-[source,shell]
-----
-$ fontisan variable FONT_FILE [--format FORMAT]
+`: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)
 
-Where,
+# Check table availability before accessing
+font.table_available?("name")  # => true
+font.table_available?("GSUB")  # => false
 
-`FONT_FILE`:: Path to the variable font file
-`FORMAT`:: Output format: `text` (default), `json`, or `yaml`
+# Access allowed tables
+font.table("name")  # => Works
+font.table("head")  # => Works
 
+# Restricted tables return nil
+font.table("GSUB")  # => nil (not loaded in metadata mode)
+----
 
-.Variable font axes and instances in Mona Sans
-[example]
-====
-[source,shell]
+You can also set loading modes via the environment:
+
+[source,ruby]
 ----
-$ fontisan variable spec/fixtures/fonts/MonaSans/variable/MonaSans[wdth,wght].ttf
+# 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)
 ----
 
-[source,text]
+The loading mode can be queried at any time.
+
+[source,ruby]
 ----
-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
-...
+# 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
 ----
-====
 
-==== Generate static instances from variable fonts
 
-Generate static font instances from variable fonts at specific variation coordinates
-and output in any supported format (TTF, OTF, WOFF).
 
-Syntax:
+=== Metadata mode
 
-[source,shell]
+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]
 ----
-$ fontisan instance VARIABLE_FONT [OPTIONS]
+font = Fontisan::FontLoader.load('font.ttf', mode: :metadata)
+puts font.family_name          # => "Arial"
+puts font.subfamily_name       # => "Regular"
+puts font.post_script_name     # => "ArialMT"
 ----
 
-Where,
+Tables loaded:
 
-`VARIABLE_FONT`:: Path to the variable font file
-`OPTIONS`:: Instance generation options
+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
 
-Options:
 
-`--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
+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
 
-.Generate bold instance at wght=700
-[example]
-====
-[source,shell]
-----
-$ fontisan instance variable.ttf --wght 700 --output bold.ttf
 
-Generating instance... done
-Writing output... done
-Static font instance written to: bold.ttf
-----
-====
+=== Full mode
 
-.Generate instance and convert to OTF
-[example]
-====
-[source,shell]
-----
-$ fontisan instance variable.ttf --wght 300 --to otf --output light.otf
+Loads all tables in the font for complete analysis and manipulation.
 
-Generating instance... done
-Writing output... done
-Static font instance written to: light.otf
+.Full mode: Complete font analysis
+[source,ruby]
 ----
-====
+font = Fontisan::FontLoader.load('font.ttf', mode: :full)
+font.table("GSUB")  # => Available
+font.table("GPOS")  # => Available
 
-.Generate instance and convert to WOFF
-[example]
-====
-[source,shell]
+# Check which mode is active
+puts font.loading_mode  # => :metadata or :full
 ----
-$ fontisan instance variable.ttf --wght 600 --to woff --output semibold.woff
 
-Generating instance... done
-Writing output... done
-Static font instance written to: semibold.woff
-----
-====
+Tables loaded:
 
-.Generate instance with multiple axes
-[example]
-====
-[source,shell]
-----
-$ fontisan instance variable.ttf --wght 600 --wdth 75 --output condensed.ttf
+* All tables in the font
+* Including GSUB, GPOS, cmap, glyf/CFF, etc.
 
-Generating instance... done
-Writing output... done
-Static font instance written to: condensed.ttf
-----
-====
+=== Lazy loading option
 
-.List available named instances
-[example]
-====
-[source,shell]
-----
-$ fontisan instance variable.ttf --list-instances
+Fontisan supports lazy loading of tables in both `:metadata` and `:full` modes.
+When lazy loading is enabled (optional), tables are only parsed when accessed.
 
-Available named instances:
+Options:
 
-  [0] Instance 4
-    Coordinates:
-      wdth: 75.0
-      wght: 200.0
+`false`:: (default) Eager loading. All tables for the selected mode are parsed
+upfront.
 
-  [1] Instance 5
-    Coordinates:
-      wdth: 75.0
-      wght: 250.0
+`true`:: Lazy loading enabled. Tables are parsed on-demand.
 
-  [2] Instance 6
-    Coordinates:
-      wdth: 75.0
-      wght: 300.0
+[source,ruby]
 ----
-====
+# Metadata mode with lazy loading (default, fastest)
+font = Fontisan::FontLoader.load('font.ttf', mode: :metadata, lazy: true)
 
-.Use named instance
-[example]
-====
-[source,shell]
-----
-$ fontisan instance variable.ttf --named-instance 0 --output thin.ttf
-----
-====
+# Metadata mode with eager loading (loads all metadata tables upfront)
+font = Fontisan::FontLoader.load('font.ttf', mode: :metadata, lazy: false)
 
-.Preview instance generation (dry-run)
-[example]
-====
-[source,shell]
+# 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)
 ----
-$ fontisan instance variable.ttf --wght 700 --dry-run
 
-Dry-run mode: Preview of instance generation
 
-Coordinates:
-  wght: 700.0
 
-Output would be written to: variable-instance.ttf
-Output
 
- format: same as input
+== Outline format conversion
 
-Use without --dry-run to actually generate the instance.
-----
-====
+=== General
 
-==== Optical size information
+Fontisan supports bidirectional conversion between TrueType (TTF) and
+OpenType/CFF (OTF) outline formats through the Fontist universal outline model
+(UOM).
 
-Display optical size range from the OS/2 table for fonts designed for specific
-point sizes.
+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
+
+Conversion uses a format-agnostic universal outline model as an intermediate
+representation, ensuring high-quality results while preserving glyph metrics and
+bounding boxes.
+
+
+=== Convert between TTF and OTF
+
+==== 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
+)
+----
 
+Using FormatConverter:
 
-.Supported scripts in Libertinus Serif Regular
-[example]
-====
-[source,shell]
+[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
-
-All commands support these options:
+**Pattern analysis**:
 
-`--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) or 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
 
@@ -2117,10 +2196,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
@@ -2132,26 +2211,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