fontisan 0.4.10 → 0.4.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 797250db52b46986a1458fd680d2c2f2eab6896ba1bcf617ba0d74622ce7ff51
-  data.tar.gz: 81cf20d3aff4f40b33e0fec8cc8de359a1a4acf139d14fe75ec3a4fc839ac827
+  metadata.gz: e97f99deb241e5abd1bbdaeb27849efb3a4597bf2139fc8a1fa815fcccbfdfcb
+  data.tar.gz: ced71eac0e00e479581c5460e33672aa80ded30cd40cb590b5a09621c5441290
 SHA512:
-  metadata.gz: dc92df9fbb61326d199f51ceda010e8f990cd109355679d463066e0f590a461e71241239b6b90f3a1acf5832362fba778d51833d24eb01c46b42b95c488c3550
-  data.tar.gz: c331cceb05fd29864a85e4e7d7dca99aa96c9c2ef152c3e877842aaffd0a82d1ad46e6770d5e80d3799bb67a905306a1eb6e5b4d18d03f5c8a02072c030c33f8
+  metadata.gz: cc72fc9f58560fddf2440ecead8a54060a06a6da38ac3de2212d893cb3dbb2dea88649c82c30ff8fb10d25389058a63770d4309e414856f031ab3d88659f4150
+  data.tar.gz: bac0c91aa712516256d2ae7fb7ccee7dd31fe1549ace5bb533ea9d2b27b7087da4b0b200412794b3677b44c43bae79c87cbcaa849db3f6d993d00dac91a1e3a3

data/README.adoc

@@ -15,7 +15,9 @@ and Adobe Type 1 fonts (OTF, TTF, OTC, TTC, dfont, PFB, PFA).
 The gem provides both a Ruby library API and a command-line interface, with
 structured output formats (YAML, JSON, text) via lutaml-model.
 
-Fontisan is designed to replace the following tools:
+Fontisan is designed to replace the following tools (see
+link:docs/FEATURE_PARITY.adoc[Feature Parity] for the full list and
+per-tool coverage):
 
 * `otfinfo` from http://www.lcdf.org/type/[LCDF Typetools]. Fontisan supports
 all features provided by `otfinfo`, including extraction of font metadata,
@@ -30,6 +32,26 @@ validation, format conversion, and collection creation. See
 link:docs/EXTRACT_TTC_MIGRATION.md[extract_ttc Migration Guide] for detailed
 command mappings and usage examples.
 
+* **Adobe AFDKO** — `makeotf`, `otf2ttf`, `ttx`, `mergeFonts`,
+  `checkOutlinesUFO`, `rotateFont`. See
+  link:docs/AFDKO_MIGRATION.adoc[AFDKO Migration Guide].
+
+* **Python fontTools + ufoLib2 + ufo2ft** — UFO model layer, UFO
+  compile pipeline (TTF/OTF/CFF2 + variable), glyph filters (8/8),
+  feature writers (GDEF, kern, mark, mkmk, curs), `pyftsubset`,
+  `pyftmerge`, `varLib`. See link:docs/UFO_COMPILATION.adoc[UFO Compilation Guide].
+
+* **`ttx` (TTX format)** — full read/write of the FontTools XML
+  format. See link:docs/TTX.adoc[TTX Support].
+
+* **Google `woff2_compress` / `woff2_decompress`** — WOFF and
+  WOFF2 compression/decompression in pure Ruby. See
+  link:docs/WOFF_WOFF2_FORMATS.adoc[WOFF/WOFF2 Formats Guide].
+
+* **Type 1 utilities** (`t1disasm`, `t1asm`, `t1embed`, `pfm2afm`)
+  — full PFB/PFA parse/generate, eexec decryption, PFM↔AFM
+  round-trip. See link:docs/TYPE1_FONTS.adoc[Type 1 Fonts Guide].
+
 
 == Installation
 
@@ -60,11 +82,15 @@ Font compilation and assembly::
 * UFO → TTF compilation with cubic-to-quadratic conversion and winding-order correction (see link:docs/UFO_COMPILATION.adoc[UFO Compilation Guide])
 * UFO → OTF (CFF1) compilation with Type 2 charstring encoding
 * UFO → OTF (CFF2) compilation with variable-font blend/vsindex operators (see link:docs/CFF2_SUPPORT.adoc[CFF2 Support Guide])
+* UFO → all binary formats via the `Ufo::Convert` dispatcher: TTF, OTF, OTF2, WOFF, WOFF2, dfont, TTC, OTC, PFB, PFA
+* UFO feature writers: GDEF glyph classification, GPOS kern/mark/mkmk/curs (see link:docs/UFO_COMPILATION.adoc[UFO Compilation Guide — Filters + Feature Writers])
+* Glyph-processing filters: cubic_to_quadratic, decompose_components, flatten_components, reverse_contour_direction, transformations, sort_contours, propagate_anchors, remove_overlaps
 * Multi-source font stitching with explicit subfont declaration and TTC/OTC collection output (see link:docs/STITCHER_GUIDE.adoc[Stitcher Guide])
 * SVG path → UFO glyph conversion for chart-extracted glyphs (see link:docs/SVG_TO_GLYF.adoc[SVG to Glyph Guide])
 * Variable font compilation: fvar, gvar, HVAR, MVAR, avar, STAT tables
 * Signature-based glyph deduplication with 65,535 glyph cap enforcement
 * Compound (composite) TrueType glyph flattening
+* AFDKO migration: drop-in replacement for `makeotf`, `otf2ttf`, `ttx`, `mergeFonts`, `checkOutlinesUFO` (see link:docs/AFDKO_MIGRATION.adoc[AFDKO Migration Guide])
 
 Color fonts and collections::
 * Color font table builders: COLR v0, CPAL, SVG table, sbix, CBDT/CBLC (see link:docs/COLOR_FONTS.adoc[Color Fonts Guide])

data/Rakefile

@@ -12,24 +12,25 @@ RuboCop::RakeTask.new
 namespace :fixtures do
   # Load centralized fixture configuration
   require_relative "spec/support/fixture_fonts"
+  require "fontisan/tasks"
 
   # Helper method to download a single file
   def download_single_file(name, url, target_path)
-    require "open-uri"
-
     puts "[fixtures:download] Downloading #{name}..."
-    FileUtils.mkdir_p(File.dirname(target_path))
 
-    URI.open(url) do |remote|
-      File.binwrite(target_path, remote.read)
-    end
+    Fontisan::Tasks::FixtureDownloader.new(
+      url: url,
+      destination: target_path,
+    ).call
 
     puts "[fixtures:download] #{name} downloaded successfully"
+  rescue Fontisan::Tasks::FixtureDownloader::Error => e
+    warn "[fixtures:download] #{name} failed after retries: #{e.message}"
+    raise
   end
 
   # Helper method to download and extract a font archive
   def download_font(name, url, target_dir)
-    require "open-uri"
     require "zip"
 
     puts "[fixtures:download] Downloading #{name}..."
@@ -39,45 +40,58 @@ namespace :fixtures do
     temp_path = File.join(Dir.tmpdir,
                           "fontisan_#{name}_#{Process.pid}_#{rand(10000)}.zip")
 
-    # Download using IO.copy_stream for better Windows compatibility
-    URI.open(url, "rb") do |remote|
-      File.open(temp_path, "wb") do |file|
-        IO.copy_stream(remote, file)
-      end
-    end
-
-    puts "[fixtures:download] Extracting #{name}..."
-
-    # Open zip file and ensure it's fully closed before we're done
-    zip_file = Zip::File.open(temp_path)
     begin
-      zip_file.each do |entry|
-        # Skip macOS metadata files and directories
-        next if entry.name.start_with?("__MACOSX/") || entry.name.include?("/._")
-        next if entry.directory?
-
-        # Ensure entry.name is relative by stripping leading slashes
-        relative_name = entry.name.sub(%r{^/+}, "")
-
-        dest_path = File.join(target_dir, relative_name)
-        FileUtils.mkdir_p(File.dirname(dest_path))
-
-        # Skip if file already exists
-        next if File.exist?(dest_path)
-
-        # Write the file content directly using binary mode
-        File.open(dest_path, "wb") do |file|
-          IO.copy_stream(entry.get_input_stream, file)
+      Fontisan::Tasks::FixtureDownloader.new(
+        url: url,
+        destination: temp_path,
+      ).call
+
+      puts "[fixtures:download] Extracting #{name}..."
+
+      # Open zip file and ensure it's fully closed before we're done
+      zip_file = Zip::File.open(temp_path)
+      begin
+        zip_file.each do |entry|
+          # Skip macOS metadata files and directories
+          next if entry.name.start_with?("__MACOSX/") || entry.name.include?("/._")
+          next if entry.directory?
+
+          # Ensure entry.name is relative by stripping leading slashes
+          relative_name = entry.name.sub(%r{^/+}, "")
+
+          dest_path = File.join(target_dir, relative_name)
+          FileUtils.mkdir_p(File.dirname(dest_path))
+
+          # Skip if file already exists
+          next if File.exist?(dest_path)
+
+          # Write the file content directly using binary mode
+          File.open(dest_path, "wb") do |file|
+            IO.copy_stream(entry.get_input_stream, file)
+          end
         end
+      ensure
+        # Explicitly close the zip file to release file handle on Windows
+        zip_file&.close
       end
     ensure
-      # Explicitly close the zip file to release file handle on Windows
-      zip_file&.close
+      # Clean up the temp zip explicitly so the temp dir doesn't fill
+      # up on repeated runs. On Windows the just-closed zip file
+      # handle can briefly hold a lock that surfaces as
+      # Errno::EACCES; swallow that one error so the rake task can
+      # complete (OS will sweep the temp file later).
+      begin
+        File.delete(temp_path) if File.exist?(temp_path)
+      rescue Errno::EACCES
+        warn "[fixtures:download] could not delete temp zip #{temp_path}; " \
+             "OS will clean it up"
+      end
     end
 
-    # Temp file left in Dir.tmpdir - OS will clean it up automatically
-
     puts "[fixtures:download] #{name} downloaded successfully"
+  rescue Fontisan::Tasks::FixtureDownloader::Error => e
+    warn "[fixtures:download] #{name} failed after retries: #{e.message}"
+    raise
   rescue LoadError => e
     warn "[fixtures:download] Error: Required gem not installed. Please run: gem install rubyzip"
     raise e

data/docs/AFDKO_MIGRATION.adoc

@@ -0,0 +1,175 @@
+= AFDKO Migration Guide
+
+This guide maps commands and concepts from Adobe Font Development
+Kit for OpenType (AFDKO) — `makeotf`, `otf2ttf`, `ttx`, `mergeFonts`,
+`rotateFont` — to their pure-Ruby equivalents in fontisan.
+
+fontisan's UFO pipeline replaces every AFDKO command for the
+compile/convert/validate workflows. No external toolchain required.
+
+== Command map
+
+[cols="1,1,3", options="header"]
+|===
+| AFDKO | fontisan | Notes
+
+| `makeotf -f font.ufo -o font.otf`
+| `fontisan ufo build font.ufo --output font.otf --to otf`
+| CFF1 output by default; pass `--to otf2` for CFF2 (variable fonts).
+
+| `makeotf -f font.ufo -o font.ttf`
+| `fontisan ufo build font.ufo --output font.ttf --to ttf`
+| TrueType (glyf) output. `cubic_to_quadratic` and
+  `reverse_contour_direction` filters run automatically.
+
+| `ttx font.ttf`
+| `fontisan ufo convert font.ttf font.ufo`
+| `ttx` produces XML; fontisan produces a typed UFO source directory.
+
+| `otf2ttf font.otf`
+| `fontisan convert font.otf font.ttf`
+| Outline conversion (CFF → glyf) is handled by the
+  `OutlineConverter` strategy; no Python required.
+
+| `mergeFonts out.ufo a.ufo b.ufo`
+| Use `Fontisan::Stitcher` (see link:STITCHER_GUIDE.adoc[Stitcher Guide])
+| Stitcher is more flexible — supports per-source codepoint remaps,
+  glyph-cap partitioning, and deduplication.
+
+| `rotateFont` (font info updates)
+| Edit `Fontisan::Ufo::Info` directly
+| fontisan exposes the full UFO model in Ruby.
+
+| `checkOutlinesUFO font.ufo`
+| `fontisan ufo validate font.ufo`
+| Plus the link:COLLECTION_VALIDATION.adoc[collection validator] for TTC/OTC.
+
+| (no AFDKO equivalent)
+| `fontisan ufo extract font.ufo A A.svg`
+| Per-glyph standalone SVG export — new in fontisan.
+|===
+
+== Compile-time options
+
+AFDKO uses a `font.ufo/lib.plist` `com.github.fonttools` manifest
+plus a `FontMenuNameDB` / `GlyphOrderAndAliasDB` file pair. fontisan
+takes those inline:
+
+[source,ruby]
+----
+ufo = Fontisan::Ufo::Font.open("font.ufo")
+ufo.info.family_name = "MyFont"
+ufo.info.postscript_full_name = "MyFont-Regular"
+
+# Apply a uniform scale before compile (AFDKO's -sh / -sz options)
+Fontisan::Ufo::Compile::Filters.apply(
+  [:transformations],
+  ufo.layers.default_layer.glyphs.values,
+  matrix: [1.1, 0, 0, 1.1, 0, 0] # 110% scale
+)
+
+Fontisan::Ufo::Convert.convert(ufo, to: :otf, output_path: "font.otf")
+----
+
+== Variable fonts
+
+AFDKO's `makeotf -f default.ufo -i instances/...` master-instance
+model maps to fontisan's `Ufo::Compile::VariableTtf` /
+`VariableOtf` compilers, which read the UFO's `fvar` + `gvar` +
+designspace data directly.
+
+[source,ruby]
+----
+ufo = Fontisan::Ufo::Font.open("MyVariable.ufo")
+Fontisan::Ufo::Compile::VariableTtf.new(ufo).compile(output_path: "MyVariable.ttf")
+----
+
+For OTF (CFF2) variable fonts, use `Compile::VariableOtf` or pass
+`to: :otf2` through the dispatcher.
+
+== Filter pipelines
+
+AFDKO has no first-class filter pipeline — you'd shell out to
+Python fontTools `ufo2ft.filters.*`. fontisan ships the equivalent
+filters in pure Ruby:
+
+[source,ruby]
+----
+glyphs = ufo.layers.default_layer.glyphs.values
+
+Fontisan::Ufo::Compile::Filters.apply(
+  %i[
+    decompose_components
+    propagate_anchors
+    cubic_to_quadratic
+    reverse_contour_direction
+    sort_contours
+  ],
+  glyphs
+)
+----
+
+Run them in this order: decompose first (so subsequent filters see
+only simple glyphs), then propagate anchors (uses base glyphs'
+anchors), then the TrueType-required conversions, finally sort.
+
+== Output formats at a glance
+
+fontisan can produce every format AFDKO can, plus a few AFDKO
+cannot:
+
+[cols="1,1", options="header"]
+|===
+| Format | Command
+
+| TrueType (`.ttf`)
+| `fontisan ufo build f.ufo --output f.ttf`
+
+| OpenType CFF1 (`.otf`)
+| `fontisan ufo build f.ufo --output f.otf --to otf`
+
+| OpenType CFF2 (`.otf`, variable)
+| `fontisan ufo build f.ufo --output f.otf --to otf2`
+
+| WOFF (compressed TTF/OTF)
+| `fontisan ufo convert f.ufo f.woff`
+
+| WOFF2 (Brotli-compressed)
+| `fontisan ufo convert f.ufo f.woff2`
+
+| Mac dfont (resource fork)
+| `fontisan ufo convert f.ufo f.dfont`
+
+| TrueType Collection (`.ttc`)
+| `fontisan ufo convert f.ufo f.ttc`
+
+| OpenType Collection (`.otc`)
+| `fontisan ufo convert f.ufo f.otc`
+
+| PostScript Type 1 Binary (`.pfb`)
+| `fontisan ufo convert f.ufo f.pfb`
+
+| PostScript Type 1 ASCII (`.pfa`)
+| `fontisan ufo convert f.ufo f.pfa`
+|===
+
+== Why migrate
+
+* **No AFDKO install** — fontisan is a Ruby gem; no separate
+  toolchain to license, install, or version-pin.
+* **No Python dependency** — fontisan is pure Ruby. Eliminates the
+  Python fontTools + ufo2ft + ufoLib2 stack from your build.
+* **Single source of truth** — fontisan reads, writes, and round-trips
+  every format. No format-specific tools.
+* **Programmatic API** — every CLI command has a Ruby equivalent
+  under `Fontisan::Ufo::*`. Scriptable in ways AFDKO shells cannot
+  match.
+
+== See also
+
+* link:UFO_COMPILATION.adoc[UFO Compilation Guide] — full reference
+  for the compile / convert / filter / CLI surface.
+* link:STITCHER_GUIDE.adoc[Stitcher Guide] — replaces `mergeFonts`
+  with codepoint remaps, partition strategies, and dedup.
+* link:CFF2_SUPPORT.adoc[CFF2 Support] — variable-font blend
+  operators.

data/docs/FEATURE_PARITY.adoc

@@ -0,0 +1,263 @@
+= Feature Parity — Tools fontisan Replaces
+
+fontisan is a pure-Ruby replacement for several established font
+toolchains. This page lists every external tool fontisan can
+substitute for, with notes on coverage and migration paths.
+
+== Adobe Font Development Kit for OpenType (AFDKO)
+
+The AFDKO ships a suite of command-line tools for font
+development. fontisan replaces every one in pure Ruby.
+
+[cols="1,1,3", options="header"]
+|===
+| AFDKO | fontisan | Notes
+
+| `makeotf -f font.ufo -o font.otf`
+| `fontisan ufo build font.ufo --output font.otf --to otf`
+| CFF1 by default; `--to otf2` for CFF2 (variable fonts).
+
+| `makeotf -f font.ufo -o font.ttf`
+| `fontisan ufo build font.ufo --output font.ttf --to ttf`
+| TrueType (glyf). `cubic_to_quadratic` +
+  `reverse_contour_direction` filters run automatically.
+
+| `ttx font.ttf` / `ttx font.ttx`
+| `fontisan export font.ttf --format ttx` / `fontisan info font.ttx`
+| See link:TTX.adoc[TTX Support]. Byte-compatible output for
+  typed tables.
+
+| `otf2ttf font.otf`
+| `fontisan convert font.otf font.ttf`
+| Outline conversion (CFF → glyf) via `OutlineConverter`.
+
+| `mergeFonts out.ufo a.ufo b.ufo`
+| `Fontisan::Stitcher` (see link:STITCHER_GUIDE.adoc[Stitcher Guide])
+| More flexible: per-source codepoint remaps, partition
+  strategies (Plane/Block/Script), glyph-cap enforcement,
+  deduplication.
+
+| `rotateFont` (font-info updates)
+| Edit `Fontisan::Ufo::Info` directly
+| fontisan exposes the full UFO model in Ruby.
+
+| `checkOutlinesUFO font.ufo`
+| `fontisan ufo validate font.ufo`
+| Plus the link:COLLECTION_VALIDATION.adoc[collection validator]
+  for TTC/OTC.
+
+| (no AFDKO equivalent)
+| `fontisan ufo extract font.ufo A A.svg`
+| Per-glyph standalone SVG export.
+|===
+
+link:AFDKO_MIGRATION.adoc[AFDKO Migration Guide] → full command
+reference and pipeline examples.
+
+== LCDF Typetools (`otfinfo`)
+
+`otfinfo` from http://www.lcdf.org/type/[LCDF Typetools] is the
+canonical font-metadata display tool. fontisan replaces it
+entirely.
+
+[cols="1,1", options="header"]
+|===
+| otfinfo | fontisan
+
+| `otfinfo -i font.otf`
+| `fontisan info font.otf`
+
+| `otfinfo --brief font.otf` (fast)
+| `fontisan info font.otf --brief` (~5× faster, metadata-only)
+
+| Per-flag queries (`--family`, `--postscript-name`, etc.)
+| `--fields` flag selects specific fields
+|===
+
+fontisan supports every field `otfinfo` produces, plus extras
+(color capabilities, variable-font detail, OpenType layout
+features). The `info` command auto-detects file format from
+magic bytes — never trusts extensions.
+
+== `extract_ttc`
+
+https://github.com/fontist/extract_ttc[extract_ttc] extracts
+fonts from a TrueType/OpenType Collection (`.ttc`/`.otc`).
+fontisan replaces it with Docker-style subcommands:
+
+[source,bash]
+----
+# extract_ttc
+extract_ttc font.ttc
+
+# fontisan
+fontisan collection ls font.ttc      # list faces
+fontisan collection info font.ttc    # per-face metadata
+fontisan collection extract font.ttc # write each face to disk
+----
+
+link:docs/EXTRACT_TTC_MIGRATION.md[extract_ttc Migration Guide] →
+full command mapping.
+
+== Python fontTools + ufoLib2 + ufo2ft
+
+fontTools is the dominant Python font library. fontisan replaces
+its core surfaces in pure Ruby:
+
+[cols="1,1,3", options="header"]
+|===
+| fontTools / ufoLib2 / ufo2ft | fontisan | Coverage
+
+| `fontTools.ttx` (TTX I/O)
+| `Fontisan::Export::TtxParser` + `TtxGenerator` (see link:TTX.adoc[TTX])
+| Typed read/write of every standard table.
+
+| `ufoLib2` (UFO model layer)
+| `Fontisan::Ufo::*` (16 model classes)
+| Substantially complete. Allotments: Info, Font, Layer, LayerSet,
+  Glyph, Contour, Point, Component, Anchor, Guideline, Image,
+  Kerning, Features, Lib, DataSet, ImageSet.
+
+| `ufo2ft.compile*` (UFO compile)
+| `Fontisan::Ufo::Compile::TtfCompiler` / `OtfCompiler` /
+  `Otf2Compiler` / `VariableTtf` / `VariableOtf`
+| Full compile pipeline. TTF, OTF (CFF1), OTF2 (CFF2), variable.
+
+| `ufo2ft.filters.*` (glyph filters)
+| `Fontisan::Ufo::Compile::Filters::*`
+| 8/8: cubic_to_quadratic, decompose_components,
+  flatten_components, reverse_contour_direction, transformations,
+  sort_contours, propagate_anchors, remove_overlaps (bbox approx).
+
+| `ufo2ft.featureWriters.*` (GSUB/GPOS writers)
+| `Fontisan::Ufo::Compile::FeatureWriters::*`
+| 6/6 commonly-needed: Kern, Kern2, Gdef, Mark, Mkmk, Curs. Each
+  returns structured data for the table builders to encode.
+
+| `fontTools.subset` (pyftsubset)
+| `Fontisan::Subset::*` + `fontisan subset` CLI
+| Profiles: PDF, web, minimal. Codepoint subset + table
+  stripping.
+
+| `fontTools.merge` (pyftmerge)
+| `Fontisan::Stitcher` (see link:STITCHER_GUIDE.adoc[Stitcher Guide])
+| More flexible than pyftmerge: explicit per-face codepoint
+  binding, deduplication, partition by plane/block/script.
+
+| `fontTools.varLib` (variable font assembly)
+| `Fontisan::Ufo::Compile::VariableTtf` / `VariableOtf` /
+  `Avar` / `Hvar` / `Mvar` / `Stat` / `Gvar` / `Fvar`
+| Full variable-font compile from UFO masters.
+|===
+
+== Type 1 font tools
+
+fontisan parses and generates Type 1 fonts (`.pfb`, `.pfa`),
+replacing several specialty tools:
+
+[cols="1,1,3", options="header"]
+|===
+| Tool | fontisan | Notes
+
+| `t1disasm` / `t1asm` (Type 1 dis/assembler)
+| `Fontisan::Type1::PfbParser` / `PFBGenerator` /
+  `PFAGenerator`
+| Round-trips PFB ↔ Type 1 charstring tokens.
+
+| `t1embed` / `t1unembed` (font embedding)
+| `Fontisan::Type1::Decryptor` + charstring layer
+| Eexec decryption + charstring de-encryption.
+
+| PFM Tools (`pfm2afm`, etc.)
+| `Fontisan::Type1::PfmParser` + `AfmGenerator`
+| Round-trip PFM ↔ AFM.
+|===
+
+link:TYPE1_FONTS.adoc[Type 1 Fonts Guide] → full reference.
+
+== WOFF / WOFF2 compress / decompress
+
+[cols="1,1,3", options="header"]
+|===
+| Tool | fontisan | Notes
+
+| Google `woff2_compress`
+| `Fontisan::Converters::WoffWriter`
+| zlib compression for WOFF.
+
+| Google `woff2_decompress`
+| `Fontisan::FontLoader.load` (auto-detects WOFF2)
+| Decompresses to in-memory TTF/OTF.
+
+| Google `woff2_compress` (Brotli)
+| `Fontisan::Converters::Woff2Encoder`
+| Brotli compression for WOFF2 with optional table transforms.
+|===
+
+link:WOFF_WOFF2_FORMATS.adoc[WOFF/WOFF2 Formats Guide] → full
+reference.
+
+== Variable font tools
+
+[cols="1,1,3", options="header"]
+|===
+| Tool | fontisan | Notes
+
+| `fontTools.varLib.instancer`
+| `Fontisan::Variation::Optimizer` + `InstantiateCommand`
+| Generates static instances from a variable font.
+
+| `fontTools.varLib.merger`
+| `Fontisan::Ufo::Compile::VariableTtf` / `VariableOtf`
+| Merges UFO masters into a variable font.
+
+| `fontTools.ttLib` variable-font table read/write
+| `Tables::Fvar`, `Tables::Gvar`, `Tables::Avar`, `Tables::Hvar`,
+  `Tables::Vvar`, `Tables::Mvar`, `Tables::Stat`
+| Full read/write for every variation table.
+|===
+
+link:VARIABLE_FONT_OPERATIONS.adoc[Variable Font Operations] →
+full reference.
+
+== Validation
+
+[cols="1,1,3", options="header"]
+|===
+| Tool | fontisan | Notes
+
+| `fontTools.fontBuilder` (validation hooks)
+| `Fontisan::Validators::*` (DSL framework)
+| Profiles: indexability, usability, production, web,
+  spec_compliance, default. Each profile = set of checks.
+
+| `fontTools.ttx` round-trip checks
+| `fontisan validate font.ttf`
+| Runs every check in the chosen profile.
+|===
+
+link:VALIDATION.adoc[Validation Guide] → full reference.
+
+== What fontisan does NOT replace
+
+For honesty:
+
+* **Glyph editing GUI** — fontisan is a library, not a font
+  editor. Use FontForge, Glyphs, RoboFont, or FontLab for visual
+  editing; use fontisan for the build/inspect/validate pipeline.
+* **Glyph drawing from scratch** — fontisan reads/writes outline
+  data but has no canvas/drawing primitives. Generate outlines in
+  an editor or programmatically via the UFO model.
+* **Bitmap font rendering** — fontisan is for font files, not
+  rasterizing text. Use HarfBuzz + a renderer for that.
+* **Heavy polygon clipping** — fontisan's `remove_overlaps`
+  filter uses a bounding-box approximation. For production-grade
+  boolean ops, preprocess in FontLab or use the `clipper` gem.
+
+== See also
+
+* link:UFO_COMPILATION.adoc[UFO Compilation Guide]
+* link:TTX.adoc[TTX Support]
+* link:STITCHER_GUIDE.adoc[Stitcher Guide]
+* link:AFDKO_MIGRATION.adoc[AFDKO Migration Guide]
+* link:EXTRACT_TTC_MIGRATION.md[extract_ttc Migration Guide]