fontisan 0.4.23 → 0.4.25

data/TODO.improvements/03-fontisan-audit-command.md

@@ -0,0 +1,189 @@
+# 03 — `fontisan audit` command (identity+style+features lens)
+
+## Priority
+P1
+
+## Problem
+
+The `fontist-archive-private` pipeline currently reaches into Fontisan internals to extract font identity + metadata:
+
+```ruby
+# Current (wrong) approach — manual cmap + table poking
+font = Fontisan::FontLoader.load(font_path)
+cmap = font.table("cmap")
+codepoints = cmap ? cmap.unicode_mappings.keys : []
+# ...plus ad-hoc reads of name, OS/2, head, fvar, GSUB, GPOS
+```
+
+Fragile and bypasses Fontisan's API. Fontisan has `InfoCommand` (font metadata) and `UnicodeCommand` (codepoint/glyph mappings), but neither produces a complete, self-describing audit record suitable for archival use.
+
+## Goal
+
+A `fontisan audit` command that produces a structured **font audit report** (YAML or JSON) covering what ucode's audit does NOT:
+
+- **Identity** — name-table strings (family, full, PostScript, version)
+- **Style** — OS/2 weight/width classes, head macStyle, fsSelection italic/bold, panose, fvar axes
+- **Coverage facts** — total codepoints, total glyphs, cmap subtable provenance, optional codepoint list
+- **OpenType layout** — GSUB/GPOS scripts (distinct from Unicode scripts), features list
+- **Provenance** — `generated_at`, `fontisan_version`, `source_sha256`
+
+## MECE split with ucode
+
+ucode owns the Unicode-coverage axis (UCD parsing, block/script aggregation, per-codepoint glyph extraction). fontisan owns the font-identity axis.
+
+| Concern | Owner |
+|---------|-------|
+| UCD fetching + parsing | ucode |
+| Block/script aggregation from codepoints | ucode |
+| Per-codepoint SVG extraction | ucode |
+| HTML browsers | ucode |
+| Font identity (name table) | **fontisan audit** |
+| Style metadata (OS/2, head, fvar) | **fontisan audit** |
+| OpenType scripts + features | **fontisan audit** |
+| Source provenance (sha256, fontisan_version) | **fontisan audit** |
+| cmap subtable provenance | **fontisan audit** |
+
+**The fontisan audit does NOT bundle UCDXML parsing.** Block aggregation is delegated: fontisan audit accepts an optional pre-built ucode index path, OR emits the codepoint list and lets the consumer (fontist-archive) run ucode separately.
+
+## Beyond ucode: revised priority after self-debate
+
+A critical self-debate (see commit history) culled several "diagnostic" features that overlap with existing tools. The surviving axes:
+
+### Keep — high value, fontisan-unique
+- **Identity + Style + Features** — justified for archival format (one YAML per face, with provenance). NOT a general font inspector.
+- **Subset report** — when fontisan subsets, emit a structured report (glyph/codepoint/table breakdown). Web font engineers hit this daily; pyftsubset emits minimal output. fontisan has the subset infrastructure.
+- **Cross-format equivalence** — `fontisan equivalent font.ttf font.woff2` → true/false + diff. Catches CDN regeneration bugs from stale masters. fontTools diffs are too noisy.
+- **License/rights extraction** — OS/2 fsType embedding bits, name ID 13 license, head macStyle commercial-use hints. Compliance teams need this before redistribution. Currently buried.
+- **Collection integrity** — narrow (CJK foundries, Apple system fonts) but real for that audience. Cheap to add once identity extraction exists.
+
+### Drop — overlap with established tools
+- ~~**OTS-rejection predictor**~~ — Chromium ships `ots-sanitize`, the actual tool Chrome uses. Reimplementing in Ruby means we're always behind Chrome's evolving rule set. Better: wrap ots-sanitize as subprocess.
+- ~~**Format-round-trip report**~~ — WOFF2 is lossless by design; report would say "nothing changed" 99% of the time. TTF↔OTF outline-fidelity is a real check but it's one function, not an audit axis.
+- ~~**Variable-font readiness**~~ — **fontbakery** owns this space. Hundreds of mature checks, Google Fonts uses it for every submission. Don't compete; wrap if needed.
+- ~~**Hinting audit**~~ — audience is ~50 people worldwide. Modern web fonts ship largely unhinted. VF fonts don't use TT hints. Specialized tools (FontLab, ttfautohint) serve this niche better.
+
+### Maybe later — niche but real
+- **Performance profile** — glyph count, table-level bytes, predicted parse time. Mobile/embedded niche. Apple has internal tools; nothing public.
+- **Identity hash** — canonical hash of (name + post + head + OS/2 identity) surviving lossless conversion. CDN/asset-pipeline use case.
+
+The headline correction: the original proposal positioned fontisan audit as a "font inspector" competing with commodity tools. The actually-valuable features are **workflow-specific reports** (subset, conversion equivalence, license) that leverage fontisan's unique subsetting + conversion infrastructure. ucode can't do any of these.
+
+## Approach
+
+### Models (`lib/fontisan/models/audit/`)
+
+Use `lutaml-model` like all other fontisan models:
+
+- `AuditReport` — top-level report, attributes per the schema below
+- `AuditAxis` — variable-font axis descriptor
+- `AuditFeature` — feature tag + scripts list
+
+### Command (`lib/fontisan/commands/audit_command.rb`)
+
+`Commands::AuditCommand` orchestrates — does NOT re-parse tables. Delegates to existing commands:
+
+- `InfoCommand` — identity + name-table strings
+- `UnicodeCommand` — codepoint list + cmap subtable provenance
+- `ScriptsCommand` — `opentype_scripts`
+- `FeaturesCommand` — `features`
+- `FormatDetector` — `source_format`
+
+This makes `AuditCommand` a thin orchestration layer.
+
+### CLI (`lib/fontisan/cli.rb`)
+
+```bash
+# Standalone
+fontisan audit Inter-Regular.ttf                    # → stdout (YAML)
+fontisan audit Inter-Regular.ttf -o report.yaml     # → file
+fontisan audit Inter-Regular.ttf --format json      # → stdout (JSON)
+
+# Collection
+fontisan audit Inter.ttc -o reports/                # → reports/Inter.ttc/{00..08}-*.yaml
+
+# Single face from collection
+fontisan audit Inter.ttc --font-index 6 -o Inter-Bold.yaml
+```
+
+### Output schema (one face per file)
+
+```yaml
+generated_at: 2026-07-10T12:30:00Z
+fontisan_version: 0.4.24
+source_file: Inter-Regular.ttf
+source_sha256: 3b1a...
+source_format: ttf
+
+font_index: null
+num_fonts_in_source: 1
+
+# Identity
+family_name: Inter
+subfamily_name: Regular
+full_name: Inter Regular
+postscript_name: Inter-Regular
+version: Version 4.000;git-a52131595
+font_revision: 4.0
+
+# Style
+weight_class: 400
+width_class: 5
+italic: false
+bold: false
+panose: "2 0 5 3 0 0 0 0 0 0"
+is_variable: false
+axes: []
+
+# Coverage
+total_codepoints: 2857
+total_glyphs: 1486
+cmap_subtables: [4, 12, 14]
+codepoints: [U+0000, U+0020, ...]   # omitted with --no-codepoints
+
+# OpenType layout
+opentype_scripts: [latn, cyrl]
+features: [kern, liga, calt]
+```
+
+### Collection layout
+
+```
+reports/
+  Inter.ttc/
+    00-Inter-Regular.yaml
+    01-Inter-Italic.yaml
+    ...
+    08-Inter-Black.yaml
+```
+
+Filename pattern: `{font_index:02d}-{postscript_name}.yaml`. Index prefix guarantees face-order sort and disambiguates broken fonts where two faces share a PostScript name.
+
+## Out of scope
+
+- UCDXML parsing (ucode's domain)
+- Block/script aggregation (consumer runs ucode separately, OR a future `--with-ucode` flag calls ucode as a subprocess)
+- HTML browsers (ucode's domain)
+- Per-codepoint glyph extraction (ucode's 4-tier resolver)
+- Reading formula YAML — this command reports what the FONT FILE declares
+- Generating WOFF specimens (ConvertCommand's domain)
+
+## Effort
+
+~1-2 days.
+
+## Dependencies
+
+None directly. Existing commands (`InfoCommand`, `UnicodeCommand`, `ScriptsCommand`, `FeaturesCommand`) provide the data; `AuditCommand` just orchestrates.
+
+## Acceptance criteria
+
+- New spec `spec/fontisan/commands/audit_command_spec.rb` covers:
+  - Standalone TTF → YAML + JSON output
+  - Collection TTC → directory of N face reports
+  - `--font-index N` → single-face report
+  - `--no-codepoints` omits the codepoint list
+  - Source sha256 matches `Digest::SHA256.file(path)`
+  - Variable font with fvar → axes array populated
+- New spec `spec/fontisan/models/audit_report_spec.rb` covers the model's serialization.
+- CLI smoke test verifies `fontisan audit path/to/font.ttf` produces valid YAML on stdout.
+- README/docs updated.

data/TODO.improvements/04-ufo-composite-glyph-encoding.md

@@ -0,0 +1,46 @@
+# 04 — UFO composite glyph encoding
+
+## Priority
+P1
+
+## Problem
+
+`Ufo::Compile::GlyfLoca` (`lib/fontisan/ufo/compile/glyf_loca.rb:137`) emits simple glyphs only. UFO sources with composite glyphs (e.g., é defined as a component reference to e + acute) lose their component structure on compile — the compiled glyf either drops them or depends on `flatten_components` filter pre-processing.
+
+## Goal
+
+`GlyfLoca` encodes composite glyphs natively per OpenType spec section 5.6. A UFO `<component>` element maps to a glyf component record referencing the target glyph by index, preserving the original transform.
+
+## Approach
+
+Add a `CompositeEncoder` collaborator in `lib/fontisan/ufo/compile/glyf_loca/composite_encoder.rb` that takes a UFO `<component>` plus a GID-resolver (component name → compiled GID) and emits the binary component record per OT spec:
+
+```
+uint16 flags
+uint16 glyphIndex
+(uint8|uint8|uint8|uint8 | int8|int8|int8|int8 | uint8) args  # depends on flags bits 0/1
+(F2Dot14 × 4 | F2Dot14 × 2 | F2Dot14) transformation  # depends on flags bits 7/6/3
+```
+
+`GlyfLoca` invokes the encoder when a UFO glyph has components (no contours, OR contours + components — latter is rare but spec-legal).
+
+The existing `flatten_components` filter remains for callers who want pre-flattening (e.g., for fonts that target renderers without component support).
+
+## Out of scope
+
+- Variable-font composite variation deltas (`gvar`) — separate concern, TODO 06's blast radius.
+- Cycling component references (A → B → A) — these need pre-validation, tracked separately.
+
+## Effort
+
+~1 day.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- New spec covers encoding of all 8 component arg/transform combinations (flags bit patterns).
+- Round-trip spec: UFO with composite → compile → re-read via `FontLoader` → components match original.
+- The `flatten_components` filter still works as a pre-pass for callers that want flattened output.

data/TODO.improvements/05-otf-compiler-real-cff.md

@@ -0,0 +1,63 @@
+# 05 — OTF compiler real CFF charstrings
+
+## Priority
+P1
+
+## Problem
+
+`Ufo::Compile::OtfCompiler` (`lib/fontisan/ufo/compile/otf_compiler.rb:9`) currently emits a placeholder CFF table — no real charstrings. Any OTF output is incomplete:
+
+```
+# TODO.full/10: this currently emits a placeholder CFF table
+# real charstrings. Full CFF construction lands when TODO 10
+```
+
+The font loads but renders nothing useful. Production OTF output is blocked.
+
+## Goal
+
+`OtfCompiler` emits a complete CFF table with:
+- Real Type 2 charstrings for every glyph (converted from UFO contours)
+- Valid Top DICT (font matrix, charset, encoding, CharStrings INDEX offset)
+- Valid Private DICT (default width, nominal width, SubrZERO subroutines if any)
+- Correct name INDEX, charset, FDSelect/FDArray (for CID-keyed fonts)
+
+Round-trip: UFO → compile → re-read via `FontLoader` → contours match.
+
+## Approach
+
+Reuse the Type 2 charstring conversion logic from `lib/fontisan/type1/charstring_converter.rb` — UFO contours → moveto/lineto/curveto closepath is structurally identical to Type 1 → Type 2 charstring conversion.
+
+Add a new `CffBuilder` collaborator under `lib/fontisan/ufo/compile/otf_compiler/cff_builder.rb` that owns:
+
+1. **Top DICT construction** — font matrix, ROS (if CID), charstrings offset.
+2. **CharString INDEX** — per-glyph Type 2 charstring bytes.
+3. **Charset** — glyph name → GID map (uses post.names if available; else `gid{N}`).
+4. **Private DICT** — default width, nominal width, hint-mask operators (no-op when source has no hints).
+5. **Global / local subroutines** — empty INDEXs initially; TODO 06 wires hint subroutines.
+
+The existing `Tables::Cff` BinData record already declares the on-disk structure; the builder produces the values to populate it.
+
+## Out of scope
+
+- CFF2 (variable fonts) — TODO 06.
+- Subroutine packing / optimization — `Optimizers::SubroutineOptimizer` already exists for Type 1; CFF equivalent is a separate task.
+- CID-keyed fonts with multi-FD — single FD only initially.
+
+## Effort
+
+~2-3 days.
+
+## Dependencies
+
+None (the placeholder CFF was the only thing blocking, and we're replacing it).
+
+## Acceptance criteria
+
+- New spec `spec/fontisan/ufo/compile/otf_compiler/cff_builder_spec.rb` covers:
+  - Single-glyph font (`.notdef` + one outline) → valid CFF
+  - Multi-glyph font with quadratic curves → charstrings use rcurveto correctly
+  - Multi-glyph font with TrueType cubic curves → curve conversion to Type 2 cubic
+  - Charset ordering matches maxp.numGlyphs
+- Round-trip: UFO → OTF → re-read → contours match (within Type 2 quantization tolerance)
+- `fontisan convert font.ufo --to otf` produces a font that loads in fontTools and Chrome.

data/TODO.improvements/06-cff2-blend-vsindex-operators.md

@@ -0,0 +1,51 @@
+# 06 — CFF2 blend/vsindex operators
+
+## Priority
+P2
+
+## Problem
+
+`Ufo::Compile::VariableOtf` (`lib/fontisan/ufo/compile/variable_otf.rb:12`) emits static CFF2 only:
+
+```
+- CFF2 outlines (static — blend/vsindex operators are TODO 07/18)
+TODO 07 (blend/vsindex) and TODO 18 (blend integration) to be
+```
+
+Variable CFF2 fonts (e.g., variable OTF output from a UFO with `fvar` + `gvar`-equivalent masters) can't round-trip. The compiled font is static — variation deltas are dropped.
+
+## Goal
+
+`VariableOtf` emits CFF2 with `blend` and `vsindex` operators per CFF2 spec section 3.A.4. A variable UFO source compiles to a variable OTF that renders correctly at any chosen instance along each axis.
+
+## Approach
+
+Two pieces:
+
+1. **CharString encoder** — extend the Type 2 charstring builder (from TODO 05) to emit `blend` after each variation-aware value. The master value is the default; deltas for each region are pushed on the stack then summed via `blend`.
+
+2. **ItemVariationData emission** — translate the UFO master model (`gvar`-equivalent: per-glyph deltas keyed by region) into CFF2's `ItemVariationData` and `ItemVariationStore` structures. Reuse `Ufo::Compile::ItemVariationStore` which already handles this for the variable-TTF path.
+
+3. **Region detection** — pre-pass over `fvar` axes + master locations to compute the set of variation regions. Same algorithm as `Ufo::Compile::Fvar`.
+
+## Out of scope
+
+- HVAR/VVAR/MVAR tables for variable OTF — those are outside CFF2 but already partially supported; track separately if needed.
+- Backwards-compat with non-variable CFF fonts — separate concern.
+- Subroutine packing of variation-aware charstrings — TODO follow-up.
+
+## Effort
+
+~3-5 days. CFF2 charstring semantics are intricate.
+
+## Dependencies
+
+- TODO 05 (OTF compiler real CFF) — must land first; the CFF2 builder extends the CFF builder.
+
+## Acceptance criteria
+
+- New spec covers:
+  - Single-axis variable font → CFF2 with correct `blend` operators + `ItemVariationStore`
+  - Multi-axis variable font → region table correct, no cross-axis contamination
+  - Instance generation via `Variation::InstanceGenerator` produces output identical to direct master compile (within tolerance)
+- Round-trip: UFO with fvar + masters → variable OTF → re-read → `fvar` axes match, instances render correctly.

data/TODO.improvements/07-cpal-v1-header-fields.md

@@ -0,0 +1,71 @@
+# 07 — CPAL v1 header fields
+
+## Priority
+P2
+
+## Problem
+
+`Tables::Cpal` (`lib/fontisan/tables/cpal.rb:106,184`) only parses CPAL v0 fields. CPAL v1 adds:
+
+- `numPaletteEntryLabels` (uint16) — count of palette entry labels
+- `numPaletteLabels` (uint16) — count of palette labels
+- `paletteEntryLabelsOffset` (uint32) — offset to label records
+- `paletteLabelsOffset` (uint32) — offset to label records
+
+These attach human-readable names (via the `name` table) to color palettes and entries. Fonts with CPAL v1 lose this metadata on parse.
+
+## Goal
+
+`Tables::Cpal` parses v1 header fields and exposes:
+
+- `palette_labels` — array of name-record IDs, one per palette
+- `palette_entry_labels` — array of name-record IDs, one per palette entry index
+
+Round-trip preserves the labels.
+
+## Approach
+
+Extend the BinData record in `lib/fontisan/tables/cpal.rb`:
+
+```ruby
+class Cpal < Binary::BaseRecord
+  uint16 :version
+  uint16 :num_palette_entries
+  uint16 :num_palettes
+  uint16 :num_color_records
+  uint32 :color_records_offset
+  array :color_record_indices, type: :uint16, initial_length: :num_palettes
+  # v0 ends here
+
+  # v1 extension — only present when version >= 1
+  choice :v1_fields, onlyif: -> { version >= 1 } do
+    uint16 :num_palette_entry_labels
+    uint16 :num_palette_labels
+    uint32 :palette_entry_labels_offset
+    uint32 :palette_labels_offset
+  end
+end
+```
+
+After BinData parse, lazily walk the label offsets to populate `palette_labels` and `palette_entry_labels` arrays.
+
+For emission: if v1 fields are set, include them; else emit v0.
+
+## Out of scope
+
+- CPAL v2 changes (none — v1 is the latest defined).
+- Building new palettes from scratch — just parse + emit.
+
+## Effort
+
+~4 hours.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- New spec covers parse of a synthetic CPAL v1 table with both label arrays.
+- Round-trip: v1 table → read → `to_binary_s` → identical bytes.
+- v0 tables still parse and emit unchanged.

data/TODO.improvements/08-cff-standard-string-table.md

@@ -0,0 +1,52 @@
+# 08 — CFF standard string table
+
+## Priority
+P2
+
+## Problem
+
+`Tables::Cff` (`lib/fontisan/tables/cff.rb:419`) ships only a partial standard string table (the 391 predefined Type 1 / CFF strings per spec appendix A). Glyph names that should be in the standard set are duplicated in the custom strings index, wasting space and breaking round-trip fidelity with fontTools.
+
+## Goal
+
+Complete the 391-string standard table per CFF spec. `Cff` parses glyph names against the standard table; only non-standard names go in the custom strings index.
+
+## Approach
+
+Replace the partial list with the canonical 391 strings (spec appendix A, also in fontTools' `fontTools.cffLib.strings`).
+
+Add a class method:
+
+```ruby
+class Cff < Binary::BaseRecord
+  STANDARD_STRINGS = [...].freeze  # 391 entries
+
+  def self.standard_string?(name)
+    STANDARD_STRINGS.include?(name)
+  end
+
+  def self.standard_string_index(name)
+    STANDARD_STRINGS.index(name)
+  end
+end
+```
+
+Update the CFF builder (TODO 05's `CffBuilder`) to skip custom-string encoding when a name is standard.
+
+## Out of scope
+
+- CID-keyed fonts (no name strings) — unaffected.
+- Custom charstring-internal names (operator names) — those are operators, not string IDs.
+
+## Effort
+
+~2 hours.
+
+## Dependencies
+
+- TODO 05 (OTF compiler real CFF) benefits; doesn't strictly block.
+
+## Acceptance criteria
+
+- Spec covers: every standard name → correct index, every non-standard name → custom index.
+- Round-trip: CFF with mixed standard/non-standard names → read → emit → identical bytes.

data/TODO.improvements/09-type1-seac-expansion.md

@@ -0,0 +1,57 @@
+# 09 — Type 1 seac expansion
+
+## Priority
+P2
+
+## Problem
+
+`Type1::CharStringConverter` (`lib/fontisan/type1/charstring_converter.rb:161`) and `Type1::TtfToType1Converter` (`lib/fontisan/type1/ttf_to_type1_converter.rb:256`) emit seac operators as-is when converting Type 1 → TrueType. seac (Standard Encoding Accented Character) composites two glyphs into one — e.g., é = e + acute at a fixed offset. Modern renderers deprecated seac; Type 1 → TTF conversion must expand it into actual outlines.
+
+## Goal
+
+`TtfToType1Converter` (and the reverse path) expands seac into merged outlines:
+
+1. Resolve the two referenced glyphs (base + accent) via the source font.
+2. Translate them to the seac offset.
+3. Concatenate their contours into the parent glyph.
+
+## Approach
+
+Add a `SeacExpander` collaborator under `lib/fontisan/type1/seac_expander.rb` that takes:
+
+- A charstring with a seac operator
+- A resolver: glyph_name → charstring (for the base + accent)
+
+Returns a new charstring with the seac replaced by the merged outline operators.
+
+Walk the source's standard-encoding lookup (Adobe Standard Encoding) to map seac's two uint8 operands to glyph names. Decode the operands:
+
+```
+seac: asb base accent
+  asb     — sidebearing (unused in expansion)
+  base    — Adobe Standard Encoding index of the base glyph
+  accent  — Adobe Standard Encoding index of the accent glyph
+```
+
+The expander recursively expands seac in base/accent glyphs (seac can nest).
+
+## Out of scope
+
+- seac in CFF (not Type 1) — CFF deprecated seac entirely; should be a warning, not an expansion.
+- Replacing the deprecated `seac` operator in TTF → Type 1 conversion — seac emission is already removed; we only need to handle source seac on input.
+
+## Effort
+
+~6 hours.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- Spec covers:
+  - Single-level seac (e.g., é) → expanded to merged outline.
+  - Nested seac (e.g., a glyph that references another seac glyph as its base) → fully expanded.
+  - seac referencing a missing glyph → raise `SeacReferenceError` with the missing name.
+- Round-trip: Type 1 with seac → TTF → re-read → outline matches the merged shape.

data/TODO.improvements/10-ufo-image-set-feature-writers.md

@@ -0,0 +1,71 @@
+# 10 — UFO image set + feature writers
+
+## Priority
+P2
+
+## Problem
+
+Two UFO subsystems ship as stubs:
+
+- `Ufo::ImageSet` (`lib/fontisan/ufo/image_set.rb:6`) — placeholder, "real implementation lands with TODO 02 (glyph model + images)"
+- `Ufo::Features` (`lib/fontisan/ufo/features.rb:8`) — placeholder, "TODO 08 (feature writers)"
+
+UFO sources with `features.fea` (OpenType layout compilation from text) or images (UFO 3 image data) lose both on round-trip.
+
+## Goal
+
+### ImageSet
+- `Ufo::ImageSet` parses UFO 3 image data: reads `images/` directory, exposes `images` array of `Ufo::Image` records with filename + sha + PNG bytes.
+- `Ufo::Glyph#image` (already modeled) reads image references; round-trips.
+- Compile: glyphs with image references emit `CBDT`/`CBLC` color-bitmap entries (reusing the BinData models from PR #106).
+
+### Features (feature writers)
+- `Ufo::Features` parses `features.fea` via a new `FeatureCompiler` collaborator.
+- Compiles OpenType layout rules (kern, liga, calt, etc.) into `GSUB`/`GPOS` tables.
+- Output tables are mergeable into the compiled font.
+
+## Approach
+
+### ImageSet
+Reuse existing `Tables::Cbdt`/`Cblc` BinData records. Convert each UFO image to a small-metrics-format PNG block. Build CBLC IndexSubTableArray pointing at each block.
+
+For test fixtures: the existing `CbdtFixture` (PR #107) already builds valid CBDT/CBLC pairs — use as reference for the emission shape.
+
+### Features
+Use a fea-syntax parser. Options:
+- **Inline parser** — non-trivial; ~5 days work, ~500 LOC.
+- **Adapter for `fontTools.feaLib`** — only available with Python; introduces cross-language dep (violates "pure Ruby" rule).
+- **Limited fea subset** — handle only kern/liga (most common); error on unsupported constructs.
+
+Recommendation: **limited fea subset** initially, expanding as real-world fonts demand.
+
+Add `FeatureCompiler` under `lib/fontisan/ufo/compile/feature_compiler.rb`. Parses `features.fea` into a tree, then emits GSUB/GPOS records. Starts with:
+- `feature kern { pair ... } kern;` → GPOS PairPos (format 1)
+- `feature liga { sub ... by ...; } liga;` → GSUB LigatureSubst
+
+## Out of scope
+
+- Adobe FEA parser completeness — full spec is 100+ pages; cover what real fonts use.
+- AFDKO integration — out of scope.
+
+## Effort
+
+- ImageSet: ~1 day (BinData + IO).
+- Features (limited subset): ~3 days (kern + liga paths).
+- Features (full fea): weeks — explicitly out of scope.
+
+## Dependencies
+
+- TODO 05 (OTF compiler real CFF) — image glyphs end up in CBDT, unrelated to CFF. No dep.
+- None blocking.
+
+## Acceptance criteria
+
+### ImageSet
+- Spec covers read of UFO with one image → `glyph.image` populated, `imageset.images.first.bytes` matches PNG bytes.
+- Compile round-trip: UFO with image glyph → TTF → re-read → CBDT/CBLC tables present, bitmap decodable.
+
+### Features
+- Spec covers a UFO with kern feature → GPOS table present with correct PairPos.
+- Spec covers a UFO with liga feature → GSUB table present with correct LigatureSubst.
+- Unsupported fea constructs raise `UnsupportedFeaError` with a clear message.

data/TODO.improvements/11-kern-groups-plist.md

@@ -0,0 +1,49 @@
+# 11 — kern groups.plist support
+
+## Priority
+P2
+
+## Problem
+
+`Ufo::Compile::FeatureWriters::Kern` (`lib/fontisan/ufo/compile/feature_writers/kern.rb:18`) reads kerning pairs from `kerning.plist` but only partially supports `groups.plist`:
+
+```
+# groups.plist data (TODO: groups.plist support is partial).
+```
+
+UFO sources that use class-based kerning (kerning classes defined in `groups.plist` instead of per-glyph) lose the class data. Compiled fonts have incomplete kern tables.
+
+## Goal
+
+`Kern` feature writer reads `groups.plist` class definitions, resolves them in `kerning.plist` lookups, and emits GPOS class-based PairPos records (format 2).
+
+## Approach
+
+Two pieces:
+
+1. **Group resolution** — when `kerning.plist` references a group name (rather than a glyph name), expand to all group members. Track group → glyph-set mapping.
+
+2. **Format-2 emission** — emit PairPos format 2 (class-based) when > N pairs share a class. Threshold: ~5 pairs (configurable). Below threshold, fall back to format 1 (pair-based) for size.
+
+Add a `KerningClassResolver` collaborator under `lib/fontisan/ufo/compile/feature_writers/kern/class_resolver.rb`. Stateless given (kerning.plist, groups.plist); returns a list of resolved pairs (glyph_a, glyph_b, value).
+
+## Out of scope
+
+- Variable-font kerning (HVAR table) — separate concern.
+- Contextual kerning (`kern` feature with context) — separate feature.
+
+## Effort
+
+~4 hours.
+
+## Dependencies
+
+None.
+
+## Acceptance criteria
+
+- Spec covers:
+  - Class-based kerning (groups.plist with two classes, kerning.plist with one pair between them).
+  - Mixed class + glyph kerning (one glyph + one class).
+  - Threshold: < 5 pairs → format 1; >= 5 pairs → format 2.
+- Round-trip: UFO with class kerning → TTF → re-read → GPOS contains the right PairPos records.