fontisan 0.2.16 → 0.2.22

data/docs/CONVERSION_GUIDE.adoc

@@ -113,12 +113,21 @@ Generating options control how the output font is written.
 | `optimize_tables` | Boolean | Enable table optimization | Reduce file size |
 | `reencode_first_256` | Boolean | Reencode first 256 glyphs | Type 1 output |
 | `encoding_vector` | String | Custom encoding vector | Type 1 output |
-| `compression` | String | Compression: zlib, brotli, none | Web font output |
-| `transform_tables` | Boolean | Transform tables for output | Format-specific transformations |
+| `zlib_level` | Integer (0–9) | zlib compression level | WOFF output (default 6) |
+| `uncompressed` | Boolean | Store tables uncompressed | WOFF only (legal per WOFF 1.0 §5.1) |
+| `compression_threshold` | Integer | Skip compression for tables < N bytes | WOFF only (default 100) |
+| `brotli_quality` | Integer (0–11) | Brotli quality | WOFF2 output (default 11) |
+| `transform_tables` | Boolean | Apply glyf/loca + hmtx transformations | WOFF2 only |
+| `metadata_xml` | String | Optional WOFF metadata XML | WOFF only |
+| `private_data` | String | Optional WOFF private data | WOFF only |
 | `preserve_metadata` | Boolean | Preserve copyright/license metadata | Maintain font metadata |
 | `strip_metadata` | Boolean | Remove metadata | Reduce file size |
 | `target_format` | String | Collection target format | Collection conversions |
 
+Compression knobs are declared by each strategy (`WoffWriter`, `Woff2Encoder`)
+via the `ConversionStrategy` DSL. `FormatConverter.validate_options_for_target!`
+rejects knobs that don't apply to the requested target format.
+
 === CLI Option Mapping
 
 ==== Opening Options
@@ -388,7 +397,7 @@ Notes: dfont supports both TrueType and OpenType/CFF, or mixed formats.
 Fontisan::ConversionOptions.from_preset(:web_optimized)
 # From: :otf, To: :woff2
 # opening: {}
-# generating: { compression: "brotli", transform_tables: true,
+# generating: { brotli_quality: 11, transform_tables: true,
 #              optimize_tables: true, preserve_metadata: true }
 ----
 
@@ -398,8 +407,10 @@ Benefits: 30-50% smaller than TTF/OTF
 
 [source,ruby]
 ----
-# generating: { compression: "zlib", preserve_metadata: true,
-#              add_private_data: false }
+Fontisan::ConversionOptions.from_preset(:legacy_web)
+# From: :otf, To: :woff
+# generating: { zlib_level: 9, optimize_tables: true,
+#              preserve_metadata: true }
 ----
 
 ==== Type 1 → WOFF/WOFF2
@@ -410,8 +421,8 @@ Workflow: Type 1 → OTF → WOFF2
 ----
 # Via OTF intermediate
 # opening: { decompose_composites: false, generate_unicode: true }
-# generating: { compression: "brotli" }  # WOFF2
-# OR compression: "zlib"    # WOFF
+# generating: { brotli_quality: 11 }    # WOFF2
+# OR generating: { zlib_level: 9 }      # WOFF
 ----
 
 === SVG Font Generation
@@ -481,7 +492,7 @@ Optimize fonts for web delivery:
 Fontisan::ConversionOptions.from_preset(:web_optimized)
 # From: :otf, To: :woff2
 # opening: {}
-# generating: { compression: "brotli", transform_tables: true,
+# generating: { brotli_quality: 11, transform_tables: true,
 #              optimize_tables: true, preserve_metadata: true }
 ----
 
@@ -491,6 +502,18 @@ Use cases:
 * Reducing page load time
 * Bandwidth optimization
 
+=== legacy_web
+
+WOFF with maximum zlib compression for legacy browser reach (IE 9+):
+
+[source,ruby]
+----
+Fontisan::ConversionOptions.from_preset(:legacy_web)
+# From: :otf, To: :woff
+# generating: { zlib_level: 9, optimize_tables: true,
+#              preserve_metadata: true }
+----
+
 === archive_to_modern
 
 Convert font archives to modern format:

data/docs/EXTRACT_TTC_MIGRATION.md

@@ -246,7 +246,7 @@ fontisan maintains 100% backward compatibility:
 
 = ExtractTTC to Fontisan Migration Guide
 
-This guide helps users migrate from https://github.com/fontist/extract_ttc[ExtractTTC] to Fontisan.
+This guide helps users migrate from [ExtractTTC](https://github.com/fontist/extract_ttc) to Fontisan.
 
 Fontisan provides complete compatibility with all ExtractTTC functionality while adding comprehensive font analysis, subsetting, validation, and format conversion capabilities.
 

data/docs/WOFF_WOFF2_FORMATS.adoc

@@ -74,6 +74,59 @@ $ fontisan convert INPUT.ttf --to woff --output output.woff
 $ fontisan convert INPUT.ttf --to woff2 --output output.woff2
 ----
 
+=== Choosing between WOFF and WOFF2
+
+WOFF and WOFF2 use different compression algorithms, fixed by their specs.
+The format you choose **is** the choice of algorithm — there is no separate
+`--compression` flag.
+
+[options="header"]
+|====
+| Format | Algorithm | Compatibility              | Typical size
+| WOFF  | zlib   | All browsers (legacy-safe)    | baseline
+| WOFF2 | Brotli | Modern browsers only          | ~30% smaller than WOFF
+|====
+
+If you need to support old browsers that lack Brotli decoders, use WOFF:
+
+[source,shell]
+----
+$ fontisan convert INPUT.ttf --to woff --output out.woff --zlib-level 9
+----
+
+For modern-only delivery, WOFF2 is preferred:
+
+[source,shell]
+----
+$ fontisan convert INPUT.ttf --to woff2 --output out.woff2
+----
+
+Note: WOFF2 mandates Brotli, WOFF mandates zlib. The container format is the
+algorithm selector — you cannot mix and match.
+
+==== Per-format compression knobs
+
+Each container exposes only the knobs that apply to it. Options declared for
+the wrong target format raise a clear `ArgumentError` at convert time.
+
+[options="header"]
+|====
+| Format | Knob                       | Range / values | Default
+| WOFF   | `--zlib-level`             | 0–9            | 6
+| WOFF   | `--uncompressed`           | (flag)         | off
+| WOFF   | `--compression-threshold`  | bytes          | 100
+| WOFF2  | `--brotli-quality`         | 0–11           | 11
+| WOFF2  | `--[no-]transform-tables`  | (flag)         | off
+|====
+
+The same knobs are available on the Ruby API via keyword arguments:
+
+[source,ruby]
+----
+Fontisan.convert("f.ttf", to: :woff,  output: "f.woff",  zlib_level: 9)
+Fontisan.convert("f.ttf", to: :woff2, output: "f.woff2", brotli_quality: 11)
+----
+
 .Conversion with optimization
 [example]
 ====

data/docs/api/conversion-options.md

@@ -51,6 +51,7 @@ options = Fontisan::ConversionOptions.from_preset(:type1_to_modern)
 | `type1_to_modern` | Type 1 | OTF |
 | `modern_to_type1` | OTF | Type 1 |
 | `web_optimized` | OTF | WOFF2 |
+| `legacy_web` | OTF | WOFF |
 | `archive_to_modern` | TTC | OTF |
 
 ### new(**kwargs)
@@ -96,19 +97,28 @@ Opening options control source font processing.
 
 Generating options control output font writing.
 
-| Option | Type | Default |
-|--------|------|---------|
-| `write_pfm` | Boolean | false |
-| `write_afm` | Boolean | false |
-| `write_inf` | Boolean | false |
-| `select_encoding_automatically` | Boolean | false |
-| `hinting_mode` | String | 'preserve' |
-| `decompose_on_output` | Boolean | false |
-| `write_custom_tables` | Boolean | true |
-| `optimize_tables` | Boolean | false |
-| `compression` | String | nil |
-| `transform_tables` | Boolean | false |
-| `preserve_metadata` | Boolean | true |
+| Option | Type | Default | Applies to |
+|--------|------|---------|------------|
+| `write_pfm` | Boolean | false | Type 1 output |
+| `write_afm` | Boolean | false | Type 1 output |
+| `write_inf` | Boolean | false | Type 1 output |
+| `select_encoding_automatically` | Boolean | false | Type 1 output |
+| `hinting_mode` | String | 'preserve' | All outline conversions |
+| `decompose_on_output` | Boolean | false | All outline conversions |
+| `write_custom_tables` | Boolean | true | All |
+| `optimize_tables` | Boolean | false | All |
+| `zlib_level` | Integer (0–9) | 6 | WOFF only |
+| `uncompressed` | Boolean | false | WOFF only |
+| `compression_threshold` | Integer (bytes) | 100 | WOFF only |
+| `brotli_quality` | Integer (0–11) | 11 | WOFF2 only |
+| `transform_tables` | Boolean | false | WOFF2 only |
+| `metadata_xml` | String | nil | WOFF only |
+| `private_data` | String | nil | WOFF only |
+| `preserve_metadata` | Boolean | true | All |
+
+Compression knobs are declared by each strategy (`WoffWriter`, `Woff2Encoder`)
+via the `ConversionStrategy` DSL. `FormatConverter.validate_options_for_target!`
+rejects knobs that don't apply to the requested target format.
 
 ## Examples
 
@@ -131,11 +141,24 @@ Fontisan::FontWriter.write(font, 'output.woff2', options: options)
 
 ```ruby
 options = Fontisan::ConversionOptions.new(
+  from: :ttf,
+  to: :woff2,
   opening: { autohint: true },
   generating: {
     hinting_mode: 'auto',
     optimize_tables: true,
-    compression: 'brotli'
+    brotli_quality: 11,
+    transform_tables: true
   }
 )
 ```
+
+### WOFF with Max zlib (Legacy Browser Reach)
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  from: :ttf,
+  to: :woff,
+  generating: { zlib_level: 9, preserve_metadata: true }
+)
+```

data/docs/api/font-loader.md

@@ -40,9 +40,11 @@ font = Fontisan::FontLoader.load(File.read('font.ttf', mode: 'rb'))
 
 **Raises:** Fontisan::FormatError if format is unsupported
 
-### detect_format(source)
+### detect_format(path)
 
-Detect font format without loading.
+Detect a font's on-disk format from its content (magic bytes). The file
+extension is ignored — a `.ttc` that actually contains a single OpenType-CFF
+font is reported as `:otf`.
 
 ```ruby
 format = Fontisan::FontLoader.detect_format('font.ttf')
@@ -52,24 +54,28 @@ format = Fontisan::FontLoader.detect_format('font.otf')
 # => :otf
 
 format = Fontisan::FontLoader.detect_format('font.pfb')
-# => :type1
+# => :pfb
+
+format = Fontisan::FontLoader.detect_format('font.pfa')
+# => :pfa
 ```
 
-**Returns:** Symbol or nil
+**Returns:** Symbol (`:ttf`, `:otf`, `:ttc`, `:otc`, `:woff`, `:woff2`,
+`:dfont`, `:pfa`, `:pfb`) or `nil` if the format is not recognised.
 
 ## Supported Formats
 
-| Format | Detection | Notes |
-|--------|-----------|-------|
-| TTF | Magic number | TrueType |
-| OTF | Magic number | OpenType/CFF |
-| TTC | Magic number | TrueType Collection |
-| OTC | Magic number | OpenType Collection |
-| WOFF | Magic number | Web Open Font Format |
-| WOFF2 | Magic number | Web Open Font Format 2 |
-| PFB | Marker byte | Adobe Type 1 Binary |
-| PFA | Text | Adobe Type 1 ASCII |
-| dfont | Magic number | Apple Data Fork |
+| Symbol  | Detection   | Notes                          |
+|---------|-------------|--------------------------------|
+| `:ttf`   | Magic bytes | TrueType                       |
+| `:otf`   | Magic bytes | OpenType / CFF                 |
+| `:ttc`   | Magic bytes | TrueType Collection            |
+| `:otc`   | Magic bytes | OpenType Collection            |
+| `:woff`  | Magic bytes | Web Open Font Format           |
+| `:woff2` | Magic bytes | Web Open Font Format 2         |
+| `:pfb`   | Marker byte | Adobe Type 1 Binary            |
+| `:pfa`   | Text header | Adobe Type 1 ASCII             |
+| `:dfont` | Magic bytes | Apple Data-Fork resource fork  |
 
 ## Examples
 

data/docs/cli/audit.md

@@ -0,0 +1,337 @@
+---
+title: audit
+---
+
+# audit
+
+Produce a complete per-face font audit report — identity, style, metrics,
+coverage, licensing, hinting, color capabilities, variable-font detail,
+OpenType layout features, and Unicode/CLDR aggregation.
+
+`audit` is the successor to `otfinfo`: it covers everything `otfinfo`
+reports plus a great deal more (coverage, hinting, color, variation,
+layout, language coverage), and supports collections, compare mode, and
+whole-library summaries.
+
+## Quick Reference
+
+```bash
+# One face
+fontisan audit FONT.ttf
+
+# Collection (one report per face)
+fontisan audit COLLECTION.ttc
+
+# Whole library
+fontisan audit DIR/ --recursive --summary
+
+# Compare two fonts or saved reports
+fontisan audit --compare A.ttf B.ttf
+```
+
+## Variants
+
+| Variant | What it does | Output |
+|---------|-------------|--------|
+| `audit FONT.ttf` | One AuditReport for the single face | `AuditReport` |
+| `audit COLLECTION.ttc` | One AuditReport per face (in source order) | `Array<AuditReport>` |
+| `audit DIR/ --recursive --summary` | Walk the directory, summarize the library | `LibrarySummary` |
+| `audit --compare A B` | Diff two faces or two saved reports | `AuditDiff` |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--format FORMAT` | Output format: `text` (default), `yaml`, `json` |
+| `--output PATH`, `-o` | Write to a directory (collection/library), a file (single/compare), or stdout |
+| `--font-index N` | Audit only face N of a collection (default: all) |
+| `--brief` | Fast inventory — skip metrics/hinting/color/layout/UCD/CLDR |
+| `--all-codepoints` | Include the full per-codepoint list (defaults to a compact range view) |
+| `--ucd-version VER` | Aggregate against this UCD version (`latest` to probe) |
+| `--with-language-coverage` | Compute CLDR language coverage % (auto-downloads CLDR on first use) |
+| `--cldr-version VER` | CLDR version to use (`latest` to probe) |
+| `--compare` | Diff two inputs (requires exactly two paths) |
+| `--recursive` | Library mode: walk into subdirectories |
+| `--summary` | Library mode: produce a `LibrarySummary` over a directory |
+
+## Brief Mode
+
+`--brief` runs only the cheap name-table extractors (provenance, identity,
+style, licensing, coverage) and skips metrics, hinting, color,
+variation, OpenType layout, UCD block/script aggregation, and CLDR
+language coverage. Useful for taking a fast inventory of large libraries.
+
+```bash
+fontisan audit FONT.ttf --brief
+fontisan audit DIR/ --recursive --summary --brief
+```
+
+Note: `audit --brief` is distinct from `info --brief`. `info --brief`
+loads only 6 tables; `audit --brief` still loads the full font (Coverage
+reads `cmap`) but selects a cheaper extractor subset.
+
+## Single-Face Audit
+
+```bash
+# Text formatter (default)
+fontisan audit FONT.ttf
+
+# YAML (machine-readable)
+fontisan audit FONT.ttf --format yaml
+
+# JSON
+fontisan audit FONT.ttf --format json | jq '.licensing'
+
+# Write to disk
+fontisan audit FONT.ttf -o report.yaml
+```
+
+Sample text output (truncated):
+
+```
+NotoSans-Regular
+================================================================================
+generated_at: 2026-06-24T18:11:39Z      fontisan: 0.2.20
+source_sha256: f5f552c8c5edb61fe6efb824baf4d4de47b1a8689ab4925ff43f7bd6a4ebece5
+source_file:   /path/to/NotoSans-Regular.ttf
+source_format: ttf                      layout: single face (1/1)
+
+IDENTITY
+  Family:           Noto Sans
+  Subfamily:        Regular
+  Full name:        Noto Sans Regular
+  PostScript:       NotoSans-Regular
+  Version:          Version 2.015; ttfautohint (v1.8.4.7-5d5b)
+  Revision:         2.0149993896484375
+
+STYLE
+  Weight class:     400 (Regular)
+  Width class:      5 (Medium)
+  Bold:             no
+  Italic:           no
+  PANOSE:           2 11 5 2 4 5 4 2 2 4
+
+COVERAGE
+  Codepoints:       3094
+  Glyphs:           4515
+  cmap subtables:   4, 12
+  Ranges (top 10):  U+0000-U+0000, U+000D-U+000D, U+0020-U+007E, ...
+  Unicode scripts:  Latin, ...
+
+LICENSING
+  License URL:      https://scripts.sil.org/OFL
+  Embedding:        0x0000 (Editable embedding)
+
+METRICS
+  Units per em:     1000
+  Ascender:         1160
+  Descender:        -288
+  ...
+
+UNICODE BLOCKS
+  Basic Latin                   95 / 128   74.2%
+  Latin-1 Supplement            96 / 128   75.0%
+  ...
+
+VARIABLE FONT
+  Axes:             wght (100–900, default 400)
+  Named instances:  9
+
+OPENTYPE LAYOUT
+  Scripts:          latn, cyrl, grek, ...
+  Features:         c2sc, calt, case, dlig, dnom, frac, kern, liga, ...
+
+LANGUAGE COVERAGE
+  en:  99.2%
+  fr:  97.4%
+  ...
+```
+
+## Collections
+
+For TTC/OTC/dfont, one report is produced per face in source order.
+
+```bash
+# Audit every face
+fontisan audit COLLECTION.ttc
+
+# Audit only face 2
+fontisan audit COLLECTION.ttc --font-index 2
+
+# Write one file per face into a directory
+fontisan audit COLLECTION.ttc -o reports/
+
+# Resulting files use the postscript name with a 2-digit index prefix:
+# 00-NotoSans-Regular.yaml
+# 01-NotoSans-Bold.yaml
+# 02-NotoSerif-Italic.yaml
+```
+
+## Compare Mode
+
+`--compare` diffs two inputs. Each input is one of:
+
+- A previously saved audit report (`.yaml` / `.yml` / `.json`)
+- A font file (audited on-the-fly)
+
+Mixed inputs are allowed — useful for tracking a font's evolution
+against a checked-in baseline.
+
+```bash
+# Two live fonts
+fontisan audit --compare a.ttf b.ttf
+
+# Saved baseline vs. live
+fontisan audit --compare baseline.yaml new.ttf
+
+# Two saved reports
+fontisan audit --compare v1.yaml v2.yaml -o diff.yaml
+```
+
+The output is an `AuditDiff` containing:
+
+- `field_changes` — scalar field-level changes (e.g. weight_class 400 → 700)
+- `codepoints` — added/removed/unchanged codepoint counts
+- `added_features` / `removed_features`
+- `added_scripts` / `removed_scripts`
+- `added_blocks` / `removed_blocks`
+- `added_languages` / `removed_languages`
+
+## Library Mode
+
+Point `audit` at a directory with `--recursive` and/or `--summary` to
+scan a whole library of fonts.
+
+```bash
+# Flat directory
+fontisan audit lib/ --summary
+
+# Walk subdirectories
+fontisan audit lib/ --recursive --summary
+
+# YAML for downstream processing
+fontisan audit lib/ --recursive --summary --format yaml -o library.yaml
+```
+
+The output is a `LibrarySummary` containing:
+
+- `root_path`, `total_files`, `total_faces`, `scanned_extensions`
+- `aggregate_metrics` — total codepoints/glyphs/bytes summed across faces
+- `script_coverage` — per-script face counts and lists
+- `duplicate_groups` — files grouped by `source_sha256` (size > 1)
+- `license_distribution` — face counts per `license_url`
+- `per_face_reports` — the full per-face reports used to aggregate
+
+Files that fail to load (corrupt, unsupported) are listed on stderr as
+`skipped <path>` and excluded from the summary.
+
+## UCD Aggregation
+
+By default, audit aggregates codepoints against the configured-default
+UCD version, producing:
+
+- `blocks` — per-Unicode-block coverage rows (name, range, total, covered, fill_ratio, complete)
+- `unicode_scripts` — distinct scripts present in the font
+
+Override with `--ucd-version`:
+
+```bash
+# Use a specific UCD version
+fontisan audit FONT.ttf --ucd-version 16.0.0
+
+# Probe and use the latest
+fontisan audit FONT.ttf --ucd-version latest
+```
+
+Manage the local UCD cache with `fontisan ucd`:
+
+```bash
+fontisan ucd status
+fontisan ucd list
+fontisan ucd download 17.0.0
+```
+
+## CLDR Language Coverage
+
+`--with-language-coverage` computes per-language coverage % using CLDR
+exemplar sets. The first invocation downloads the CLDR data
+(~MBs); subsequent invocations use the cache.
+
+```bash
+fontisan audit FONT.ttf --with-language-coverage
+
+# Use a specific CLDR version
+fontisan audit FONT.ttf --with-language-coverage --cldr-version 45
+```
+
+Manage the CLDR cache with `fontisan cldr`:
+
+```bash
+fontisan cldr status
+fontisan cldr list
+fontisan cldr download 45
+```
+
+## Ruby API
+
+### Single face
+
+```ruby
+require "fontisan"
+
+# Returns an AuditReport for a single font, or an Array<AuditReport>
+# for a collection (one per face).
+report = Fontisan::Commands::AuditCommand.new("font.ttf",
+                                              ucd_version: "17.0.0").run
+
+puts report.family_name
+puts report.total_codepoints
+puts report.licensing.license_url
+puts report.blocks.first.fill_ratio
+```
+
+### Compare
+
+```ruby
+diff = Fontisan::Commands::AuditCompareCommand.new(
+  "baseline.yaml", "new.ttf", ucd_version: "17.0.0"
+).run
+
+diff.field_changes.each { |c| puts "#{c.field}: #{c.left} → #{c.right}" }
+puts "added codepoints: #{diff.codepoints.added_count}"
+```
+
+### Library summary
+
+```ruby
+cmd = Fontisan::Commands::AuditLibraryCommand.new(
+  "lib/", recursive: true, options: { ucd_version: "17.0.0" }
+)
+summary = cmd.run
+cmd.skipped.each { |path| warn "skipped #{path}" }
+
+summary.script_coverage.each do |row|
+  puts "#{row.script}: #{row.face_count} faces"
+end
+summary.duplicate_groups.each do |group|
+  puts "duplicate #{group.source_sha256[0,8]}: #{group.files.join(', ')}"
+end
+```
+
+### Brief mode
+
+```ruby
+# Use the audit_brief: key (NOT brief:, which would trigger metadata-only
+# font loading via BaseCommand).
+report = Fontisan::Commands::AuditCommand.new(
+  "font.ttf", audit_brief: true, ucd_version: "17.0.0"
+).run
+```
+
+## Related Commands
+
+- [info](/cli/info) — Lighter-weight font metadata (replaces `otfinfo -i`)
+- [tables](/cli/tables) — Raw OpenType table listing
+- [features](/cli/features) — Just GSUB/GPOS features
+- [scripts](/cli/scripts) — Just supported scripts
+- [validate](/cli/validate) — Pass/fail quality checks (audit is descriptive; validate is prescriptive)

data/docs/cli/convert.md

@@ -36,6 +36,15 @@ These are individual font formats that can be converted:
 | `--output FILE` | Output file path |
 | `--optimize` | Enable outline optimization |
 | `--flatten` | Flatten composite glyphs |
+| `--zlib-level=N` | WOFF only: zlib compression level (0–9, default 6) |
+| `--uncompressed` | WOFF only: store tables uncompressed (legal per WOFF 1.0 §5.1) |
+| `--compression-threshold=N` | WOFF only: skip compression for tables smaller than N bytes (default 100) |
+| `--brotli-quality=N` | WOFF2 only: Brotli quality (0–11, default 11) |
+| `--transform-tables` / `--no-transform-tables` | WOFF2 only: apply glyf/loca + hmtx transformations |
+
+The format you pick (`--to woff` vs `--to woff2`) **is** the algorithm
+choice — WOFF mandates zlib, WOFF2 mandates Brotli. Passing a WOFF knob
+to a WOFF2 target (or vice versa) exits 1 with a clear error.
 
 ## Common Workflows
 
@@ -45,8 +54,18 @@ These are individual font formats that can be converted:
 # TTF to WOFF2 (recommended for modern browsers)
 fontisan convert font.ttf --to woff2 --output font.woff2
 
-# OTF to WOFF (broader compatibility)
+# OTF to WOFF (broader compatibility — works on IE 9+)
 fontisan convert font.otf --to woff --output font.woff
+
+# Smallest possible WOFF2 (max Brotli + table transforms)
+fontisan convert font.ttf --to woff2 --output font.woff2 \
+  --brotli-quality 11 --transform-tables
+
+# WOFF with max zlib compression
+fontisan convert font.ttf --to woff --output font.woff --zlib-level 9
+
+# WOFF stored uncompressed (legal per WOFF 1.0 §5.1; useful for tooling)
+fontisan convert font.ttf --to woff --output font.woff --uncompressed
 ```
 
 ### Convert Between Outline Formats