fontisan 0.4.6 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 519952f147a10de9f78f3e30eb4456a077f35cb24099bb65781e7b1c2c4e59a3
-  data.tar.gz: c37e0f9d37bf0512cd7c0ed9be19e0eac5a9c74eb057c951d1a2dba4237c5f11
+  metadata.gz: 9957716f86dad58d8ff9b5f0bc49bc7044ab20f073bd26b5b87f09d8a5aa1cb1
+  data.tar.gz: 5ac5083c8db47532bc1331c82209c02bc6d8b7095b8f2c27c41fecced8230b32
 SHA512:
-  metadata.gz: c5702491e2326da5f357b5c89904896763c0f57dc807022b11b1d203ab1b4158372595c5059f0fff3143631323048a543e9b2f3046ded97e868d5cf105e518cc
-  data.tar.gz: 2f9f010ab0079fedfec7932313231bf7d002b2fed7af6476c459918e92e6d9c01300dac46594b64d16874b95924026bcd1a9779fe53ae1d2ea65240464256616
+  metadata.gz: e1fa7608f49e922735d6b677456cbf4864ced9a32e3e771960229f685208c67be6079f9b1bfcfc6f393c83bf8d5b7e0e158c397b618080229a14dd274718724e
+  data.tar.gz: 730148059f3819b6dd49c1f8b86ab9d2e4d8508671b54b59cc240e638472b0da0dd5e5b7187f30b09bbd12d8e149a93903097068a45ac281224f2482464fa2ea

data/BUG-stitcher-drops-isolated-cps.md

@@ -0,0 +1,58 @@
+# BUG: Stitcher drops isolated codepoints from NotoSansCuneiform (U+12399)
+
+## Status
+
+NEW — discovered 2026-07-01. Not yet addressed. Same class as the
+earlier Plane 1 drop bugs (BUG-stitcher-drops-plane1-codepoints.md)
+but at a different gid position (gid 925 of 1238).
+
+## Reproducer
+
+```ruby
+require "fontisan"
+
+src = Fontisan::FontLoader.load("NotoSansCuneiform-Regular.ttf")
+cmap = src.table("cmap").unicode_mappings
+# U+12399 → gid 925 (font has 1239 glyphs total)
+
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:cuneiform, src)
+stitcher.include_notdef(from: :cuneiform)
+stitcher.include_codepoints([0x12399], from: :cuneiform)
+stitcher.write_to("/tmp/out.ttf", format: :ttf)
+
+out = Fontisan::FontLoader.load("/tmp/out.ttf")
+out.table("cmap").unicode_mappings.key?(0x12399)
+# => false  ← SILENTLY DROPPED
+```
+
+## Source font
+
+- File: `NotoSansCuneiform-Regular.ttf` (essenfont repo)
+- num_glyphs: 1239
+- cmap size: 1238
+- U+12399 → gid 925 (well within range, NOT at the top end)
+
+## Other donors affected
+
+Same pattern may affect other donors with similar cmap topology.
+Worth running the full donor_audit + coverage gap analysis to
+identify all affected codepoints.
+
+## Impact
+
+essenfont output is missing U+12399 (Cuneiform) and possibly other
+codepoints from various donors. Each donor with a similar gid layout
+may lose 1-N codepoints silently.
+
+## Suggested investigation
+
+The O(1) per-glyph extraction path (commit `f07e788`) may still have
+edge cases. gid 925 isn't at the boundary of the font — the drop is
+not a "top-end gid" issue like Kedebideri. This is an isolated drop
+in the middle of the gid range.
+
+Check the glyph at gid 925 in the source — is it empty, a composite,
+or otherwise different from its neighbors? The `Convert::FromBinData`
+fix that addressed the `next unless simple` issue may still have
+gaps for certain glyph types.

data/BUG-stitcher-drops-plane1-codepoints.md

@@ -0,0 +1,310 @@
+# BUG: Stitcher silently drops Plane 1 codepoints from some sources (and partial Plane 1 loss from others)
+
+## RESOLVED in fontisan 0.4.2 (PR #53)
+
+All four failure modes are fixed. Final status:
+
+| Failure | 0.4.0 | 0.4.1 | 0.4.2 |
+|---|---|---|---|
+| Lentariso TTF Plane 1 (Imperial Aramaic, Phoenician, Sidetic) | broken | fixed | **fixed** ✓ |
+| Kedebideri TTF top gids (Beria Erfe U+16EB5–B8, U+16ED0–D3) | broken | fixed | **fixed** ✓ |
+| Tangut OTF/CFF Plane 1 (NotoSerifTangut) | ok | broken | **fixed** ✓ |
+| CBDT passthrough (NotoColorEmoji) | ok | ok | **fixed** ✓ |
+
+### Root cause (PR #53)
+
+`Convert::FromBinData` had `next unless simple` which skipped empty
+glyphs, breaking gid → array index alignment. The O(1) per-glyph
+extraction introduced in 0.4.1 (`f07e788`) relied on that alignment
+and silently dropped cps whose gids mapped to skipped slots.
+
+PR #53 contains 3 commits:
+
+1. **`Convert::FromBinData`**: removed `next unless simple` — always
+   adds glyph to UFO (even if empty), maintaining gid → array index
+   alignment. **Root cause fix for both the original TTF bug and the
+   CFF regression.**
+2. **`Stitcher::Source#extract_cff_glyph_safe(gid)`**: for CFF
+   sources, falls back to full UFO conversion (which now has no
+   gaps).
+3. **Regression spec**: OTF/CFF Tangut test added to
+   `spec/fontisan/stitcher/cmap_preservation_spec.rb` — verifies
+   Tangut codepoints from `NotoSerifTangut.otf` survive in output.
+4. **GPOS kern writer** (TODO 08 partial): new `Compile::Gpos`
+   module builds minimal GPOS table from UFO kerning pairs.
+
+### Consumer-side validation (essenfont)
+
+Build with fontisan 0.4.2 + the full donor manifest produces:
+
+- 65,535 glyphs / 45.9MB
+- 181,515 cmap entries (was 159,764 in issue #3, +21,751)
+- 59.75% Unicode 17 coverage (was 53.00%, +6.75 pp)
+- 53 blocks complete (was 49)
+
+All affected donors round-trip 100%:
+
+| Donor | Block | CMAP → output |
+|---|---|---|
+| Lentariso | Imperial Aramaic U+10840–1085F | 31/31 |
+| Lentariso | Phoenician U+10900–1091F | 29/29 |
+| Lentariso | Sidetic U+10940–1095F | 26/26 |
+| Kedebideri | Beria Erfe U+16EA0–16EDF | 50/50 |
+| NotoSerifTangut (OTF/CFF) | Tangut U+17000–187FF | 6136/6136 |
+| NotoSerifTangut | Tangut Components U+18800–18AFF | 768/768 |
+| NotoColorEmoji (CBDT) | Emoticons U+1F600–1F64F | 80/80 |
+
+The sections below are preserved for historical reference.
+
+---
+
+## Summary
+
+Two distinct failures in `Fontisan::Stitcher` (fontisan 0.4.0) when
+stitching codepoints from certain TTF/OTF sources into a target TTF:
+
+1. **Total Plane 1 drop** — for sources that have cmap entries in
+   Plane 1 (U+10000..U+1FFFF), the Stitcher writes **none** of them
+   into the output font, even though the donor's cmap loads
+   correctly via `Fontisan::FontLoader.load`.
+2. **Partial upper-end drop** — for some sources, a small contiguous
+   run of the highest-cp Plane 1 entries is dropped, while the rest
+   of the block is preserved.
+
+
+Both failures are silent — no exception, no warning. The output font
+is missing the affected codepoints without any indication.
+
+## Reproducers
+
+### Bug 1 — Lentariso (total Plane 1 drop)
+
+```ruby
+require "fontisan"
+
+src = Fontisan::FontLoader.load("references/input-fonts/Lentariso-Regular.ttf")
+cmap = src.table("cmap")
+maps = cmap.unicode_mappings
+plane1_cps = maps.keys.select { |cp| cp >= 0x10000 && cp <= 0x1FFFF }
+# plane1_cps.size == 1934
+
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:lentariso, src)
+stitcher.include_notdef(from: :lentariso)
+stitcher.include_codepoints(plane1_cps, from: :lentariso)
+stitcher.write_to("/tmp/out.ttf", format: :ttf)
+
+out = Fontisan::FontLoader.load("/tmp/out.ttf")
+out_plane1 = out.table("cmap").unicode_mappings.keys
+                .count { |cp| cp >= 0x10000 && cp <= 0x1FFFF }
+# out_plane1 == 0
+```
+
+Sub-ranges showing the same pattern:
+- U+10840..U+1085F (Imperial Aramaic): 31 cps in donor → **0 in output**
+- U+10900..U+1091F (Phoenician): 29 cps in donor → **0 in output**
+- U+10940..U+1095F (Sidetic): 26 cps in donor → **0 in output**
+
+Other donors with Plane 1 coverage work correctly:
+- `NewGardiner.ttf` (4,537 Plane 1 cps) → all 10/10 stitched in spot-check
+- `references/input-fonts/UniHieroglyphica.ttf` (Egyptian Hieroglyphs Ext-A) → all 4,000/4,000 stitched
+
+### Bug 2 — Kedebideri (partial upper-end drop)
+
+```ruby
+require "fontisan"
+
+src = Fontisan::FontLoader.load("references/input-fonts/Kedebideri-Regular.ttf")
+cmap = src.table("cmap")
+maps = cmap.unicode_mappings
+beria_erfe = maps.keys.select { |cp| cp >= 0x16EA0 && cp <= 0x16EDF }
+# beria_erfe.size == 50
+
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:kedebideri, src)
+stitcher.include_notdef(from: :kedebideri)
+stitcher.include_codepoints(beria_erfe, from: :kedebideri)
+stitcher.write_to("/tmp/out.ttf", format: :ttf)
+
+out = Fontisan::FontLoader.load("/tmp/out.ttf")
+out_beria = out.table("cmap").unicode_mappings.keys
+              .select { |cp| cp >= 0x16EA0 && cp <= 0x16EDF }
+# out_beria.size == 42 (8 dropped)
+```
+
+The 8 dropped codepoints (always the same set):
+- `U+16EB5`, `U+16EB6`, `U+16EB7`, `U+16EB8` (consecutive)
+- `U+16ED0`, `U+16ED1`, `U+16ED2`, `U+16ED3` (consecutive)
+
+These all map to **gids 341–348** in the source font, which is the
+top end of the source's gid range (2..348). Dropped gids span the
+topmost consecutive range of the cmap; the gap at gid 340 in the
+source cmap (a missing glyph) precedes the first dropped range.
+
+## Expected
+
+All codepoints present in the source font's cmap should appear in the
+stitched output's cmap, with the same or remapped glyph references.
+
+## Actual
+
+- Lentariso: **0 / 1934** Plane 1 codepoints make it to output (100% loss)
+- Kedebideri: **42 / 50** Beria Erfe codepoints in output (16% loss, top-end)
+
+## Observed patterns
+
+- **Only Plane 1 is affected**. Plane 0 (BMP) codepoints from the
+  same sources work fine. Plane 2+ codepoints (FSung-2, ~61,000 cps
+  in CJK Extension B-E) work fine.
+- **The total-drop case (Lentariso) is consistent across multiple
+  runs** — every Plane 1 cp is dropped, not just some.
+- **The partial-drop case (Kedebideri) drops exactly the topmost
+  consecutive range of cmap gids** that correspond to Plane 1 entries
+  whose gids are adjacent.
+- Other Plane 1 sources work fine (NewGardiner, UniHieroglyphica),
+  so the bug is not a blanket "Plane 1 unsupported" — something about
+  the cmap structure or font topology triggers it.
+
+## What's been ruled out
+
+- cmap gids exceeding `maxp.num_glyphs` — verified all source gids
+  are within num_glyphs for both Lentariso (maxp=6063, cmap=5767)
+  and Kedebideri (maxp=380, cmap=347).
+- File format / validation — both sources load without warning via
+  `Fontisan::FontLoader.load`; their cmaps are introspectable and
+  show all expected entries.
+- Lentariso Plane 0 cps work (e.g., U+0041 → 'A' round-trips).
+- FSung-2's Plane 2 cps (CJK Ext B, ~61k entries) work end-to-end.
+
+## Suggested investigation directions
+
+1. **cmap format detection** — sources may be reported as format 4
+   (BMP-only) by fontisan's parser when they actually have a format
+   12 subtable. If the Stitcher writes only format 4 to the output,
+   all Plane 1 entries would be dropped.
+2. **`Stitcher::Source#bitmap_mode`** — added in fontisan 0.4 (per
+   CHANGELOG entry for the recent Stitcher rewrite). If Lentariso is
+   misclassified as `:cbdt` or `:none` despite being a pure `glyf`
+   source, its cmap could be ignored or partially processed.
+3. **gid adjacency in cmap** — the Kedebideri drop (gids 341–348)
+   sits at the topmost consecutive run of cmap gids. If the Stitcher
+   has a cutoff based on "n gids before the cmap max gid", this
+   could explain it. The exact mechanism is unclear without reading
+   the Stitcher internals.
+4. **Lookback into Stitcher's `assemble_cmap`** — the function that
+   merges source cmaps into the output cmap is the most likely site
+   of the bug. Check whether it iterates source cmap entries
+   sorted by glyph id or by codepoint, and whether it has any
+   boundary conditions on either sort key.
+
+## Impact
+
+- **essenfont** (this project's v0.1.0 output font) silently loses
+  86+ codepoints in Sidetic / Imperial Aramaic / Phoenician, and 8
+  in Beria Erfe. Coverage in `scripts/coverage_report.rb` shows the
+  affected blocks as 0% (or partial), even though the source fonts
+  contain valid glyphs.
+- Any downstream consumer of the Stitcher that combines Plane 1
+  donors is affected.
+
+## Related
+
+- fontisan 0.4.0 added single-source CBDT/CBLC passthrough (commit
+  `b612058`); this Stitcher bug may have been introduced in the
+  same refactor. If so, the fix should land in 0.4.x.
+
+## Test fixtures
+
+The above reproducers use donor fonts committed to the essenfont
+repo at `references/input-fonts/`:
+- `Lentariso-Regular.ttf` (Bryndan W. Meyerholt, OFL, sha256 514ac442c9c5c361625da0755e84baaee36bbafe098138312f5285c3bd2fa0d3)
+- `Kedebideri-Regular.ttf` (SIL International, OFL, sha256 f95907a8c39c68d557c2264fcf593a858eb4751cd5e0c3c7c53e1ef354444064)
+
+Both files are also available from the upstream sources documented in
+`essenfont/references/input-fonts/ATTRIBUTIONS.md`.
+
+## Reporter
+
+essenfont project, issue #3 (https://github.com/fontist/essenfont/issues/3)
+
+## Regression introduced by the fix (2026-06-30)
+
+The `feature/stitcher-perf` branch fixes the Lentariso + Kedebideri
+bugs but introduces a **new** silent Plane 1 drop for OTF/CFF sources.
+
+### New reproducer
+
+```ruby
+require "fontisan"
+
+# NotoSerifTangut is OTF (CFF outlines, no glyf table)
+src = Fontisan::FontLoader.load("NotoSerifTangut-Regular.otf")
+cmap = src.table("cmap")
+maps = cmap.unicode_mappings
+tangut = maps.keys.select { |cp| cp >= 0x17000 && cp <= 0x187FF }
+# tangut.size == 6136
+
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:tangut, src)
+stitcher.include_notdef(from: :tangut)
+stitcher.include_codepoints(tangut.first(10), from: :tangut)
+stitcher.write_to("/tmp/out.ttf", format: :ttf)
+
+out = Fontisan::FontLoader.load("/tmp/out.ttf")
+outmaps = out.table("cmap").unicode_mappings
+present = tangut.first(10).count { |cp| outmaps.key?(cp) }
+# present == 0  ← ALL DROPPED
+```
+
+Source has tables: `["CFF ", "GDEF", "GPOS", "GSUB", "OS/2", "VORG",
+"cmap", "head", "hhea", "hmtx", "maxp", "name", "post", "vhea",
+"vmtx"]`. Note `CFF ` (CFF outlines), no `glyf`.
+
+### Affected donors (essenfont manifest)
+
+| Donor | Plane 1 cps | In output | Loss |
+|---|---|---|---|
+| **noto-serif-tangut** (OTF/CFF) | 6916 | **0** | **100%** ← full regression |
+| noto-sans (TTF) | 88 | 84 | 4 cps |
+| noto-sans-sharada (TTF) | 96 | 95 | 1 cp |
+| noto-sans-math (TTF) | 1228 | 1200 | 28 cps |
+| noto-music (TTF) | 549 | 537 | 12 cps |
+| noto-sans-symbols-2 (TTF) | 1608 | 1596 | 12 cps |
+| lentariso (TTF) | 1934 | 1930 | 4 cps |
+| egyptian-text (TTF) | 1131 | 1118 | 13 cps |
+| uni-hieroglyphica (TTF) | 5108 | 5095 | 13 cps |
+| new-gardiner (TTF) | 4537 | 4524 | 13 cps |
+
+**Total: 6,916 Tangut cps + ~100 cps across 9 TTF donors = ~7,000 cps lost.**
+
+### Suggested cause
+
+The `b3e52af` commit ("stitcher: O(1) per-glyph extraction instead
+of O(n) full-donor conversion") likely changed the per-glyph
+extraction path to assume `glyf` outlines. For OTF/CFF sources,
+extraction silently fails and the cp is dropped from the output cmap.
+
+The smaller losses (~1-3% per TTF donor) may be a separate issue —
+perhaps an off-by-one or boundary condition in the new
+extraction loop. Worth grepping the new spec files for boundary
+test cases.
+
+### Net impact on essenfont
+
+- Before fix (0.4.0): 181,354 cmap entries, 59.69% Unicode 17 coverage
+- After fix (feature/stitcher-perf): 174,599 entries, 57.47% coverage
+- **Net change: −6,755 entries, −2.22 percentage points**
+
+The fix trades Lentariso + Kedebideri coverage (94 cps regained) for
+Noto Serif Tangut coverage (6,916 cps lost). Net negative.
+
+### Recommended next step
+
+The Stitcher's per-glyph extraction needs to handle:
+- TTF / `glyf` sources (current path)
+- OTF / `CFF ` sources (currently broken — likely the regression)
+- CBDT/CBLC sources (works in 0.4.0+ for single-source passthrough)
+
+All three glyph-storage modes should round-trip identically. A
+parametric spec covering each mode for the same test codepoint
+would prevent this class of regression.

data/BUG-stitcher-gid-cap-65535.md

@@ -0,0 +1,110 @@
+# BUG: Stitcher repair pass drops 3,004 cmap entries (gid remap)
+
+## Status
+
+NEW — discovered 2026-07-01 with fontisan 0.4.6. Introduced by the
+repair pass added alongside the compound-glyph flatten fix
+(commit `73820f1`). Not yet addressed.
+
+## Summary
+
+The build output's post-write repair step reports:
+
+```
+repairing: 3004 cmap entries pointed to non-existent gids (max gid = 65534)
+repaired: 132623 valid cmap entries retained
+```
+
+3,004 cmap entries that were correctly assembled by the Stitcher
+are silently dropped because the output font's gid space caps at
+65,534 and the repair step removes any cmap entry whose gid exceeds
+that limit.
+
+## Reproducer
+
+Build essenfont with the full donor manifest (30+ donors, ~160k
+codepoints in the union). The build output shows:
+
+```
+158247/158247 codepoints stitched
+=== Writing Essenfont-Regular.ttf ===
+  repairing: 3004 cmap entries pointed to non-existent gids (max gid = 65534)
+  repaired: 132623 valid cmap entries retained
+```
+
+3,004 cps are dropped, reducing coverage from expected ~96% to ~82%.
+
+## Root cause
+
+The output TTF has `maxp.num_glyphs = 65535` (the 16-bit maximum).
+The Stitcher assembles glyphs from 30+ donors whose combined glyph
+count exceeds 65,535. When the output font is written:
+
+1. Glyphs are assigned gids sequentially from 0 to ~160k.
+2. `maxp.num_glyphs` is clamped to 65,535 (16-bit limit).
+3. Any cmap entry whose gid ≥ 65,535 is now invalid (points past
+   the end of the glyph array).
+4. The repair pass removes those entries.
+
+The cap of 65,535 is a hard limit of the TrueType `maxp` table
+(`maxComponentElements` is uint16). Fonts with more than 65,535
+glyphs require CFF (OTF) format or `maxp` version 1.5 with the
+extended glyph range — but fontisan doesn't use either.
+
+## What's lost
+
+3,004 cmap entries are dropped. These fall into two groups:
+
+1. **Large CJK donors** (FSung-2, NotoSansKR, NotoSansNushu):
+   codepoints assigned to gids > 65,534 are silently dropped.
+   Affects ~1,000 cps from Plane 2 CJK (CJK Ext I, Compat Supp)
+   + ~800 cps from Hangul + ~200 cps from Nushu.
+
+2. **Synthetic SVG donors** (Khitan, Tulu-Tigalari, etc.):
+   codepoints from late-added synthetic donors get assigned gids
+   beyond 65,534. Affects ~1,000 cps from chart-extracted glyphs.
+
+## Suggested fixes
+
+### Option A: Switch to CFF (OTF) output
+
+CFF fonts have no 65,535 glyph cap. fontisan's `OtfCompiler` can
+write OTF output. The build would produce `Essenfont-Regular.otf`
+instead of `.ttf`. This is the cleanest fix but changes the output
+format.
+
+### Option B: Glyph deduplication
+
+Many donor glyphs are identical (e.g., the .notdef glyph appears
+in every donor). Deduplicating these before writing would reduce
+the glyph count below 65,535. Estimated savings: ~10,000 duplicate
+.notdef + whitespace glyphs.
+
+### Option C: Subfont splitting
+
+Split the output into multiple TTF files by Unicode plane (Plane 0,
+Plane 1, Plane 2, etc.) with a TTC (TrueType Collection) wrapper.
+Each subfont stays under 65,535 glyphs.
+
+### Option D: Remove non-contributing donors
+
+FSung-X (38,126 Plane 16 PUA cps) currently contributes zero
+useful codepoints to the output. Removing it from the build would
+reduce the glyph count by ~38,000, well within the 65,535 cap.
+
+Similarly, NotoSansKR's variable font has 23,174 cps but only
+11,172 are Hangul — the rest are duplicated by other donors.
+Subsetting KR to just Hangul would save ~12,000 glyphs.
+
+## Impact
+
+Coverage drops from expected ~96% to actual ~82.76%. The 3,004
+lost cps span 8+ Unicode blocks that have valid glyphs in the
+donor fonts but are silently dropped at write time.
+
+## References
+
+- Build log with repair message: `/tmp/build-svg6.log`
+- Affected blocks: CJK Ext I, CJK Compat Supp, Nushu,
+  Tulu-Tigalari, Khitan Small Script (partial), Hangul (partial)
+- Consumer: essenfont issue #3

data/CHANGELOG.md

@@ -9,6 +9,112 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `Stitcher` explicit subfont declaration model: every `include_*`
+  method accepts an `into:` keyword that names the target subfont.
+  The user controls collection structure upfront rather than relying
+  on after-the-fact splitting. Backward-compatible: without `into:`,
+  bindings route to `:default` (single-font behavior unchanged).
+- `Stitcher#write_collection(path, format:)` — writes all declared
+  subfonts as a TTC/OTC with table sharing via the existing
+  `Collection::Builder`. Each subfont compiled to TTF/OTF/CFF2 per
+  the `format:` argument. Collection format auto-selected: `:ttf` →
+  TTC, `:otf`/`:otf2` → OTC.
+- `Stitcher#subfonts` — hash of name → bindings for inspection.
+- `Stitcher#subfont_names` — declared subfont names in order.
+- `Stitcher#write_to(path, format:, subfont:)` — writes a specific
+  named subfont as a single file (default: `:default`).
+
+### Architecture note
+
+The previous design planned an after-the-fact "Splitter" that would
+break bindings into plane-based groups at write time. This was
+replaced with **explicit subfont declaration**: the user decides
+which codepoints go into which subfont, and the Stitcher serializes
+that declared structure. This is model-driven (the subfont
+assignment IS the model) and editorially honest (collection
+structure is an editorial decision, not an algorithmic one).
+
+### Added
+
+- `Fontisan::Tables::Cff2::Header` — CFF2 5-byte header builder
+  (majorVersion=2, minorVersion=0, headerSize=5, topDictSize).
+- `Fontisan::Tables::Cff2::IndexBuilder` — CFF2 INDEX builder with
+  uint32 count (vs card16 in CFF1). Supports > 65,535 entries in the
+  INDEX structure itself.
+- `Fontisan::Tables::Cff2::DictEncoder` — encodes CFF DICT operands
+  (integers + BCD reals) and operators (1-byte and 2-byte escape).
+- `Fontisan::Ufo::Compile::Cff2` — from-scratch CFF2 table builder
+  for UFO glyphs. Produces: Header + Top DICT (CharStrings + FontDICT
+  offsets) + Global Subr INDEX + CharStrings INDEX + FontDICT INDEX
+  (wrapping one FontDICT with empty PrivateDICT reference).
+- `Fontisan::Ufo::Compile::Otf2Compiler` — compiles UFO → OTF with
+  CFF2 outlines (table tag `CFF2` instead of `CFF `). Same OTTO sfnt
+  signature as CFF1.
+- `Stitcher#write_to` now accepts `format: :otf2` for CFF2 output.
+- `GlyphLimit` recognizes `:otf2` format.
+
+### Note on glyph cap
+
+CFF2 does **not** bypass the 65,535 glyph cap. Per the OpenType spec,
+the CFF2 CharStrings INDEX count must match `maxp.numGlyphs`, which is
+uint16 in all font versions. For > 65,535 glyphs, TTC (TrueType
+Collection) splitting is required. CFF2's value lies in variable font
+support (`blend`/`vsindex` operators + VariationStore), CID-keyed
+fonts (FDSelect), and improved subroutinization — not glyph count.
+
+### Added
+
+- `Fontisan::Stitcher::GlyphSignature` — deterministic SHA-256 signature
+  of a glyph's outline identity (advance width + contours + components).
+  Used to detect visually identical glyphs from different donors.
+- `Fontisan::Stitcher::Deduplicator` — registry mapping signatures to
+  canonical glyph names, enabling signature-based deduplication during
+  Stitcher assembly. Merges identical outlines from different donors
+  into a single gid, reducing the glyph count.
+- `Fontisan::Stitcher::GlyphLimit` — format-specific glyph-count caps
+  (TTF: 65,535; OTF: unlimited) and enforcement via `check!`.
+- `Fontisan::GlyphLimitExceededError` — raised when the Stitcher's
+  output exceeds the format's glyph cap, with actionable guidance
+  (switch to OTF, reduce donors, split into TTC).
+- `Stitcher.new(deduplicate: true)` — signature-based dedup is now the
+  default; pass `deduplicate: false` to disable.
+
+### Fixed
+
+- Stitcher no longer silently produces an invalid TTF (or OTF) when
+  the glyph count exceeds 65,535. Both TTF and OTF (CFF1) cap at
+  65,535 glyphs because `maxp.num_glyphs` is uint16 and the CFF1
+  CharStrings INDEX count is card16. The cap is now enforced BEFORE
+  writing, and signature-based deduplication merges identical outlines
+  to reduce the count. When dedup alone isn't enough,
+  `GlyphLimitExceededError` is raised with actionable options
+  (split into TTC, reduce donors, wait for CFF2) instead of the
+  previous behavior (silent truncation + dropped cmap entries at
+  the repair pass).
+
+### Added (previous)
+
+- `Fontisan::SvgToGlyf` — converts SVG path data (from ucode code-chart
+  extraction) into `Ufo::Glyph` objects that feed directly into the
+  existing Stitcher + TtfCompiler pipeline. The converter handles SVG
+  path commands (M/L/H/V/C/S/Q/T/Z), relative and absolute coordinates,
+  smooth-curve reflection, SVG `<g transform>` accumulation, viewBox
+  coordinate normalization, and Y-axis flipping. Cubic-to-quadratic
+  conversion and contour winding correction are handled automatically
+  by the existing `Ufo::Compile::Filters` when compiling to TTF.
+- `Fontisan::SvgToGlyf::Geometry::AffineTransform` — 2×3 matrix with
+  compose/apply, used uniformly for all coordinate operations.
+- `Fontisan::SvgToGlyf::Geometry::TransformParser` — parses SVG
+  `transform="..."` attribute (translate, scale, rotate, matrix, skew).
+- `Fontisan::SvgToGlyf::Geometry::Normalizer` — composes the viewBox →
+  font UPM normalization (Y-flip + scale) with group transforms.
+- `Fontisan::SvgToGlyf::Path::Parser` — tokenizes and parses SVG path
+  `d` strings into typed Command objects with implicit-repetition support.
+- `Fontisan::SvgToGlyf::Path::ContourBuilder` — converts commands to
+  `Ufo::Contour` objects, tracking current-point, subpath-start, and
+  control-point state for smooth-curve reflection.
+- `Fontisan::SvgToGlyf::Document` — walks SVG XML (via Nokogiri),
+  accumulating ancestor `<g>` transforms per `<path>`.
 - `Fontisan::Ufo::Compile::Avar` — builds the OpenType `avar` (Axis
   Variation) table with per-axis non-linear maps (defaults to identity
   -1/0/1 mapping).