fontisan 0.4.6 → 0.4.7

data/README.adoc

@@ -56,9 +56,19 @@ gem install fontisan
 
 == Features
 
+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])
+* 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
+
 Color fonts and collections::
-* Color font support: COLR/CPAL layered glyphs, sbix bitmap glyphs, and SVG table (see link:docs/COLOR_FONTS.adoc[Color Fonts Guide])
-* Font collection validation with per-font reporting (see link:docs/COLLECTION_VALIDATION.adoc[Collection Validation Guide])
+* Color font table builders: COLR v0, CPAL, SVG table, sbix, CBDT/CBLC (see link:docs/COLOR_FONTS.adoc[Color Fonts Guide])
+* Font collection management: pack/unpack TTC/OTC with table deduplication (see link:docs/COLLECTION_VALIDATION.adoc[Collection Validation Guide])
 
 Font analysis and information::
 * Comprehensive per-face font metadata extraction (replaces `otfinfo`) covering identity, style, metrics, codepoint coverage, licensing, hinting, color capabilities, variable-font detail, and OpenType layout features
@@ -81,21 +91,26 @@ Font operations::
 * Collection management (pack/unpack TTC/OTC/dfont files with table deduplication)
 
 Font format support::
-* TTF, OTF, TTC, OTC font formats (production ready)
+* TTF, OTF (CFF1), OTF2 (CFF2), TTC, OTC font formats (production ready)
+* CFF2 with variable-font blend/vsindex operators, FDSelect, subroutines
 * Adobe Type 1 fonts (PFB/PFA) with bidirectional conversion (see link:docs/TYPE1_FONTS.adoc[Type 1 Fonts Guide])
 * WOFF/WOFF2 format support with reading, writing, and conversion (see link:docs/WOFF_WOFF2_FORMATS.adoc[WOFF/WOFF2 Guide])
 * Apple legacy font support: 'true' signature TrueType fonts and dfont format (see link:docs/APPLE_LEGACY_FONTS.adoc[Apple Legacy Fonts Guide])
-* SVG font generation (complete)
+* SVG font generation and SVG-to-glyph conversion (complete)
 
 Font engineering::
 * Universal outline model for format-agnostic glyph representation
-* CFF CharString encoding/decoding (complete)
-* CFF INDEX structure building (complete)
-* CFF DICT structure building (complete)
+* CFF/CFF2 CharString encoding/decoding with blend operator support
+* CFF/CFF2 INDEX structure building (uint16 for CFF1, uint32 for CFF2)
+* CFF/CFF2 DICT structure building
 * TrueType curve converter for bi-directional quadratic/cubic conversion (complete)
-* Compound glyph decomposition with transformation support (complete)
-* CFF subroutine optimization for space-efficient OTF generation (preview mode)
+* Compound glyph decomposition with affine transformation flattening (complete)
+* CFF2 subroutine bias calculation and INDEX management
+* FDSelect (format 0, 3) for CID-keyed CFF2 fonts
 * Bidirectional hint conversion (TrueType ↔ PostScript) with validation (complete)
+* MATH table builder for mathematical formula layout
+* Meta table builder for tagged metadata
+* Glyph signature-based deduplication across donor fonts
 * CFF2 variable font support for PostScript hint conversion (complete)
 
 Export and interfaces::
@@ -2379,8 +2394,8 @@ Fontisan can:
 == UFO source operations
 
 fontisan reads, writes, and compiles UFO (Unified Font Object) v2/v3
-font sources into binary font formats (TTF, OTF). No AFDKO or Python
-fonttools needed.
+font sources into binary font formats (TTF, OTF, OTF2/CFF2). No AFDKO
+or Python fonttools needed.
 
 === Build a UFO to binary
 
@@ -2397,43 +2412,23 @@ The TTF compiler automatically applies:
 - `cubic_to_quadratic` filter (UFO cubic Beziers -> TTF quadratic)
 - `reverse_contour_direction` filter (TTF winding convention)
 
-=== Convert between UFO and binary
-
-[source,bash]
-----
-# UFO -> binary
-fontisan ufo convert font.ufo out.ttf --to ttf
-
-# Binary -> UFO (reverse direction)
-fontisan ufo convert font.ttf font.ufo/
-----
-
-=== Validate a UFO source
-
-[source,bash]
-----
-fontisan ufo validate font.ufo
-----
-
-Checks: glyphs present, family name set, unitsPerEm set, .notdef exists.
-
-=== Ruby API
+=== Ruby API — compile to TTF, OTF, or CFF2
 
 [source,ruby]
 ----
 require "fontisan"
 
-# Read a UFO
 font = Fontisan::Ufo::Font.open("font.ufo")
-puts font.family_name
-puts font.glyphs.size
 
-# Compile to TTF
+# TrueType (.ttf) — quadratic outlines
 Fontisan::Ufo::Compile::TtfCompiler.new(font).compile(output_path: "out.ttf")
 
-# Compile to OTF
+# OpenType/CFF1 (.otf) — cubic outlines
 Fontisan::Ufo::Compile::OtfCompiler.new(font).compile(output_path: "out.otf")
 
+# OpenType/CFF2 (.otf) — modern format, supports variable fonts
+Fontisan::Ufo::Compile::Otf2Compiler.new(font).compile(output_path: "out.otf")
+
 # Write back to UFO (round-trip)
 Fontisan::Ufo::Writer.new(font).write("out.ufo")
 
@@ -2442,12 +2437,39 @@ ttf = Fontisan::FontLoader.load("font.ttf")
 ufo = Fontisan::Ufo::Convert::FromBinData.convert(ttf)
 ----
 
+=== Variable font compilation
+
+[source,ruby]
+----
+# Variable TTF (glyf outlines)
+orchestrator = Fontisan::Ufo::Compile::VariableTtf.new(
+  font: default_font,
+  axes: [{ tag: "wght", min: 100, default: 400, max: 900 }],
+  masters: [{ font: bold_font, axes: { "wght" => 1.0 } }],
+)
+orchestrator.compile(output_path: "variable.ttf")
+
+# Variable OTF (CFF2 outlines)
+orchestrator = Fontisan::Ufo::Compile::VariableOtf.new(
+  default_font,
+  axes: [{ tag: "wght", min: 100, default: 400, max: 900 }],
+)
+orchestrator.compile(output_path: "variable.otf")
+----
+
+See link:docs/CFF2_SUPPORT.adoc[CFF2 Support Guide] for CFF2-specific
+features (blend operators, FDSelect, subroutines, VariationStore).
+
 == Font stitching
 
-The Stitcher combines glyphs from multiple source fonts into one new
-font. Sources can be UFO directories or loaded TTF/OTF files.
+The Stitcher combines glyphs from multiple source fonts into one or
+more new fonts. Sources can be UFO directories or loaded TTF/OTF files.
 
-=== Ruby API
+Every `include_*` method requires an `into:` keyword naming the target
+subfont. `write_to` requires a `subfont:` name. No defaults — the user
+controls the collection structure explicitly.
+
+=== Single font
 
 [source,ruby]
 ----
@@ -2455,32 +2477,37 @@ stitcher = Fontisan::Stitcher.new
 stitcher.add_source(:latin, Fontisan::FontLoader.load("NotoSans.ttf"))
 stitcher.add_source(:cjk, Fontisan::FontLoader.load("FSung-m.ttf"))
 
-stitcher.include_range(0x41..0x5A, from: :latin)    # A-Z
-stitcher.include_range(0x4E00..0x9FFF, from: :cjk)  # CJK Unified
-stitcher.include_notdef(from: :latin)
+stitcher.include_notdef(from: :latin, into: :main)
+stitcher.include_range(0x41..0x5A, from: :latin, into: :main)    # A-Z
+stitcher.include_range(0x4E00..0x9FFF, from: :cjk, into: :main)  # CJK
 
-stitcher.write_to("stitched.ttf", format: :ttf)
+stitcher.write_to("stitched.ttf", format: :ttf, subfont: :main)
 ----
 
-=== CLI
+=== Collection (TTC/OTC) with explicit subfonts
 
-[source,bash]
+When the glyph count exceeds 65,535 (the OpenType cap), split across
+named subfonts and write a collection:
+
+[source,ruby]
 ----
-fontisan stitch \
-  --source latin=NotoSans.ttf \
-  --source cjk=FSung-m.ttf \
-  --include-range latin=0x41-0x5A \
-  --include-range cjk=0x4E00-0x9FFF \
-  --notdef-from latin \
-  --output stitched.ttf
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:noto_sans, Fontisan::FontLoader.load("NotoSans.ttf"))
+stitcher.add_source(:noto_cjk, Fontisan::FontLoader.load("NotoSansCJK.ttf"))
+
+# Explicitly assign codepoints to named subfonts
+stitcher.include_range(0x41..0x5A, from: :noto_sans, into: :latin)
+stitcher.include_range(0x4E00..0x9FFF, from: :noto_cjk, into: :cjk)
+
+# Write as OTC with CFF2 subfonts and table deduplication
+stitcher.write_collection("out.otc", format: :otf2)
 ----
 
-=== Color emoji (CBDT/CBLC passthrough)
+=== CBDT/CBLC passthrough (color emoji)
 
 Sources with CBDT/CBLC tables (e.g. NotoColorEmoji) can be used as
 Stitcher sources. The bitmap data is propagated byte-for-byte from the
-source into the output. The Stitcher automatically detects the source's
-storage mode via `bitmap_mode`:
+source into the output.
 
 [source,ruby]
 ----
@@ -2488,22 +2515,48 @@ stitcher = Fontisan::Stitcher.new
 stitcher.add_source(:text, Fontisan::FontLoader.load("NotoSans.ttf"))
 stitcher.add_source(:emoji, Fontisan::FontLoader.load("NotoColorEmoji.ttf"))
 
-# All emoji glyphs from the CBDT source are added; the CBLC table
-# is copied byte-for-byte and references the right GIDs.
-stitcher.include_range(0x41..0x5A, from: :text)
-stitcher.include_range(0x1F600..0x1F64F, from: :emoji)
+stitcher.include_notdef(from: :text, into: :main)
+stitcher.include_range(0x41..0x5A, from: :text, into: :main)
+stitcher.include_range(0x1F600..0x1F64F, from: :emoji, into: :main)
 
-stitcher.write_to("out.ttf", format: :ttf)
+stitcher.write_to("out.ttf", format: :ttf, subfont: :main)
 # → out.ttf has glyf + CBDT + CBLC, emoji renders correctly
 ----
 
-**Constraints:**
-- Only ONE CBDT source per Stitcher (multiple raise
-  `Fontisan::MultipleCbdtSourcesError`)
-- The CBDT source is processed first (GIDs 0..N-1) so the CBLC's GID
-  references remain valid in the output
-- Multi-source CBDT merge is tracked as TODO (REVIEW
-  `TODO.full/ufo/23-cbdt-passthrough.md`)
+=== SVG path → glyph conversion
+
+Convert SVG path data (from ucode code-chart extraction) into UFO glyphs:
+
+[source,ruby]
+----
+# Single path → glyph
+glyph = Fontisan::SvgToGlyf.convert(
+  "M 0 0 L 500 0 L 500 700 Z",
+  upm: 1000,
+  codepoint: 0x10940,
+)
+
+# SVG file → glyph
+glyph = Fontisan::SvgToGlyf.from_svg_file("U+10940.svg", upm: 1000)
+
+# Directory of SVGs → font (for Stitcher#add_source)
+font = Fontisan::SvgToGlyf.from_directory("/tmp/chart-svg/Khitan", upm: 1000)
+----
+
+See link:docs/SVG_TO_GLYF.adoc[SVG to Glyph Guide] for details.
+
+=== CLI
+
+[source,bash]
+----
+fontisan stitch \
+  --source latin=NotoSans.ttf \
+  --source cjk=FSung-m.ttf \
+  --include-range latin=0x41-0x5A \
+  --include-range cjk=0x4E00-0x9FFF \
+  --notdef-from latin \
+  --output stitched.ttf
+----
 
 
 == Testing

data/benchmark/compile_benchmark.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Benchmark: large font compilation performance.
+#
+# Measures the time taken to compile a synthetic large UFO font into
+# TTF, OTF, and CFF2 OTF. Catches regressions in the charstring
+# pipeline and the table builders.
+
+require "tmpdir"
+require "fontisan"
+require "fontisan/ufo/compile"
+
+module FontisanBench
+  module_function
+
+  def build_synthetic_font(num_glyphs)
+    font = Fontisan::Ufo::Font.new
+    font.info.family_name = "Bench"
+    font.info.units_per_em = 1000
+    font.glyphs[".notdef"] = Fontisan::Ufo::Glyph.new(name: ".notdef")
+
+    num_glyphs.times do |i|
+      g = Fontisan::Ufo::Glyph.new(name: "g#{i}")
+      g.width = 500
+      g.add_unicode(0xE000 + i) if i < 0x1000
+      g.add_contour(Fontisan::Ufo::Contour.new([
+                                                 Fontisan::Ufo::Point.new(x: 0, y: 0, type: "line"),
+                                                 Fontisan::Ufo::Point.new(x: 100, y: 0, type: "line"),
+                                                 Fontisan::Ufo::Point.new(x: 100, y: 100, type: "offcurve"),
+                                                 Fontisan::Ufo::Point.new(x: 50, y: 150, type: "curve"),
+                                               ]))
+      font.glyphs["g#{i}"] = g
+    end
+    font
+  end
+
+  def measure(label)
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    yield
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+    puts format("%-40<label>s %8.<elapsed>.2f ms", label: label, elapsed: elapsed * 1000)
+    elapsed
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  ufo = FontisanBench.build_synthetic_font(1000)
+
+  Dir.mktmpdir do |dir|
+    FontisanBench.measure("TTF compile (1000 glyphs)") do
+      Fontisan::Ufo::Compile::TtfCompiler.new(ufo).compile(output_path: "#{dir}/a.ttf")
+    end
+    FontisanBench.measure("OTF compile (1000 glyphs)") do
+      Fontisan::Ufo::Compile::OtfCompiler.new(ufo).compile(output_path: "#{dir}/a.otf")
+    end
+    FontisanBench.measure("CFF2 OTF compile (1000 glyphs)") do
+      Fontisan::Ufo::Compile::Otf2Compiler.new(ufo).compile(output_path: "#{dir}/a-cff2.otf")
+    end
+  end
+
+  Dir.mktmpdir do |dir|
+    ufo_big = FontisanBench.build_synthetic_font(10_000)
+    FontisanBench.measure("TTF compile (10k glyphs)") do
+      Fontisan::Ufo::Compile::TtfCompiler.new(ufo_big).compile(output_path: "#{dir}/a.ttf")
+    end
+    FontisanBench.measure("CFF2 OTF compile (10k glyphs)") do
+      Fontisan::Ufo::Compile::Otf2Compiler.new(ufo_big).compile(output_path: "#{dir}/a-cff2.otf")
+    end
+  end
+end

data/docs/CFF2_SUPPORT.adoc

@@ -0,0 +1,184 @@
+= CFF2 Support Guide
+
+== General
+
+CFF2 (Compact Font Format version 2) is the modern PostScript outline
+format defined in OpenType 1.9+. It is required for variable OTF fonts
+that use PostScript outlines, and it replaces the legacy CFF (CFF1)
+format's Name INDEX, String INDEX, Encoding, and Charset with a
+simpler, variation-aware structure.
+
+Fontisan implements CFF2 entirely in pure Ruby. The pieces:
+
+* `Tables::Cff2::Header` — 5-byte header (major, minor, headerSize, topDictLength)
+* `Tables::Cff2::IndexBuilder` — uint32-count INDEX (CFF1 uses uint16)
+* `Tables::Cff2::DictEncoder` — DICT operand/operator encoding
+* `Tables::Cff2::FdSelect` — format 0 and format 3 FDSelect for CID-keyed fonts
+* `Tables::Cff::Cff2CharStringBuilder` — charstring builder with
+  vsindex (operator 22, replacing CFF1's hmoveto) and blend (operator 23)
+* `Ufo::Compile::Cff2` — assembles the CFF2 table from UFO glyphs
+* `Ufo::Compile::Cff2Subrs` — bias calculation + GlobalSubr/LocalSubr INDEXes
+
+== Building a CFF2 table directly
+
+[source,ruby]
+----
+glyphs = font.glyphs.values
+cff2_bytes = Fontisan::Ufo::Compile::Cff2.build(font, glyphs: glyphs)
+----
+
+For variable CFF2, pass an `ItemVariationStore`:
+
+[source,ruby]
+----
+vs_bytes = Fontisan::Ufo::Compile::ItemVariationStore.build(...)
+cff2_bytes = Fontisan::Ufo::Compile::Cff2.build(
+  font, glyphs: glyphs, variation_store: vs_bytes
+)
+----
+
+When `variation_store:` is present, it is placed between the GlobalSubr
+INDEX and CharStrings INDEX, and the Top DICT records its offset via
+operator 24.
+
+== CFF2 table layout
+
+[cols="1,3", options="header"]
+|===
+| Section | Notes
+
+| Header (5 bytes) | major=2, minor=0, headerSize=5, topDictLength=N
+
+| Top DICT | Offsets to CharStrings (op 17), Font DICT INDEX (op [12,36]),
+            VariationStore (op 24, variable fonts only), Private
+            (op 18)
+
+| GlobalSubr INDEX | uint32 count — empty by default
+
+| VariationStore | Present only for variable CFF2 fonts
+
+| CharStrings INDEX | uint32 count, one entry per glyph
+
+| Font DICT INDEX | uint32 count, wraps one or more Font DICTs
+
+| Font DICT | DICT with Private operator `[size, offset]`
+|===
+
+The Top DICT's size determines where GlobalSubr INDEX starts, which
+cascades to all subsequent offsets — a circular dependency that
+`Ufo::Compile::Cff2` resolves with fixed-point iteration (typically
+converges in 2-3 passes).
+
+== Variable charstrings: blend and vsindex
+
+CFF2 introduces two new charstring operators:
+
+[cols="1,1,3", options="header"]
+|===
+| Operator | Code | Purpose
+
+| `vsindex` | 22 | Selects the variation region scalars (replaces CFF1 `hmoveto`)
+
+| `blend` | 23 | Pops n+1 numbers per operand, blends using region scalars
+|===
+
+The blend protocol:
+
+  stack before: [base_value, delta_r0, delta_r1, ..., delta_r(n-1), n, blend]
+  stack after:  [blended_value]
+
+The blended value is `base_value + Σ(delta_i × scalar_i)` for the
+currently selected regions.
+
+`Tables::Cff::Cff2CharStringBuilder.build_variable` encodes variable
+outlines directly:
+
+[source,ruby]
+----
+charstring = Fontisan::Tables::Cff::Cff2CharStringBuilder.build_variable(
+  default_outline,
+  master_outlines: [bold_outline, light_outline],
+  num_regions: 2,
+  width: 600,
+)
+# → charstring bytes with base values + per-region deltas + blend
+----
+
+The builder tracks per-master position via
+`MasterState = Struct.new(:current_x, :current_y)` to compute relative
+deltas as the command sequence is walked. All masters must share the
+same command structure as the default outline.
+
+When all deltas for a coordinate are zero, the blend operator is
+omitted for that coordinate — visually identical output, smaller file.
+
+== FDSelect
+
+CID-keyed CFF2 fonts use FDSelect to map each GID to a Font DICT.
+`Tables::Cff2::FdSelect` supports both formats:
+
+* **Format 0** — one byte per glyph (small fonts)
+* **Format 3** — run-length encoded (large fonts with contiguous FD
+  assignments)
+
+[source,ruby]
+----
+fdselect_bytes = Fontisan::Tables::Cff2::FdSelect.build(
+  format: 3,
+  fd_indices: [0, 0, 1, 1, 1, 2]
+)
+----
+
+== Subroutines
+
+`Ufo::Compile::Cff2Subrs` provides:
+
+* `bias(count)` — subroutine bias per spec:
+  ** 107 when count ≤ 1240
+  ** 1131 when count ≤ 33800
+  ** 32768 above
+* `build_index(subrs)` — uint32 INDEX builder for both GlobalSubr and
+  LocalSubr (same structure — DRY)
+
+By default the GlobalSubr INDEX is empty (count=0). Per-FontDICT
+LocalSubr INDEXes are also empty in the static-font case.
+
+== Compiling to a CFF2 OTF
+
+The high-level path is `Ufo::Compile::Otf2Compiler`:
+
+[source,ruby]
+----
+Fontisan::Ufo::Compile::Otf2Compiler.new(font)
+  .compile(output_path: "Modern.otf")
+----
+
+For variable CFF2:
+
+[source,ruby]
+----
+orchestrator = Fontisan::Ufo::Compile::VariableOtf.new(
+  default_font,
+  master_fonts: [bold_font, light_font],
+  axes: [{ tag: "wght", min: 100, default: 400, max: 900 }],
+)
+orchestrator.compile(output_path: "Variable.otf")
+----
+
+NOTE: The current `VariableOtf` orchestrator emits a static CFF2 table
+with `fvar`, `STAT`, and `avar` for axes — the blend/vsindex operators
+exist in `Cff2CharStringBuilder` but are not yet wired through the
+default compile path. Until that integration lands, instances
+generated from the variable OTF will all render the default master.
+
+== Spec reference
+
+* https://learn.microsoft.com/en-us/typography/opentype/spec/cff2[OpenType CFF2 spec]
+* https://learn.microsoft.com/en-us/typography/opentype/spec/cff2charstr[CFF2 CharString spec]
+
+== See also
+
+* link:UFO_COMPILATION.adoc[UFO Compilation Guide] — high-level
+  compiler overview
+* link:VARIABLE_FONT_OPERATIONS.adoc[Variable Font Operations] —
+  reading and modifying existing variable fonts

data/docs/STITCHER_GUIDE.adoc

@@ -0,0 +1,151 @@
+= Stitcher Guide
+
+== General
+
+The Stitcher combines glyphs from multiple source fonts into one or
+more new fonts. Sources can be UFO directories, loaded TTF/OTF files,
+or any object responding to the `Ufo::Font` interface.
+
+The design rule: **the user controls the collection structure
+explicitly**. Every `include_*` method requires an `into:` keyword
+naming the target subfont, and `write_to` requires a `subfont:` name.
+There are no defaults and no after-the-fact splitting.
+
+== API
+
+[cols="2,3", options="header"]
+|===
+| Method | Purpose
+
+| `Stitcher.new(deduplicate: true)` | Create a stitcher; dedup is on by default
+
+| `add_source(label, font)` | Register a source font under a Symbol label
+
+| `include_range(range, from:, into:)` | Add codepoint range from `from` into `into`
+
+| `include_codepoints(cps, from:, into:)` | Add an explicit Array of codepoints
+
+| `include_gid(donor_gid, from:, into:)` | Add a specific GID from the source
+
+| `include_notdef(from:, into:)` | Convenience for `include_gid(0, ...)`
+
+| `set_info(hash)` | Override font info (family name, etc.)
+
+| `write_to(path, format:, subfont:)` | Compile one subfont to a single file
+
+| `write_collection(path, format:)` | Compile all declared subfonts into a TTC/OTC
+|===
+
+`format:` is one of `:ttf`, `:otf`, `:otf2`. For collections, `:ttf`
+produces a `.ttc` and `:otf`/`:otf2` produce an `.otc`.
+
+== Single-font example
+
+[source,ruby]
+----
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:latin, Fontisan::FontLoader.load("NotoSans.ttf"))
+stitcher.add_source(:cjk,  Fontisan::FontLoader.load("FSung-m.ttf"))
+
+stitcher.include_notdef(from: :latin, into: :main)
+stitcher.include_range(0x41..0x5A,   from: :latin, into: :main)  # A-Z
+stitcher.include_range(0x4E00..0x9FFF, from: :cjk,  into: :main) # CJK
+
+stitcher.write_to("stitched.ttf", format: :ttf, subfont: :main)
+----
+
+== Collection example (TTC/OTC)
+
+When the total glyph count would exceed 65,535 (the OpenType
+`maxp.numGlyphs` cap), split the work across named subfonts and write
+a collection:
+
+[source,ruby]
+----
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:noto_sans, Fontisan::FontLoader.load("NotoSans.ttf"))
+stitcher.add_source(:noto_cjk,  Fontisan::FontLoader.load("NotoSansCJK.ttf"))
+
+stitcher.include_range(0x41..0x5A,     from: :noto_sans, into: :latin)
+stitcher.include_range(0x4E00..0x9FFF, from: :noto_cjk,  into: :cjk)
+
+stitcher.write_collection("out.otc", format: :otf2)
+----
+
+Each subfont is compiled independently, then packed by
+`Collection::Builder` with table deduplication enabled — shared tables
+(head, name, OS/2, ...) are stored once and referenced from each
+subfont's offset table.
+
+== Glyph deduplication
+
+By default the Stitcher deduplicates glyphs across all sources using
+SHA-256 outline signatures (`Stitcher::GlyphSignature`). Two donor
+glyphs with identical width + contours + components are merged into a
+single target glyph; subsequent references are aliased by adding the
+extra codepoint to the merged glyph's unicode set.
+
+To disable deduplication (e.g., for forensic comparison):
+
+[source,ruby]
+----
+stitcher = Fontisan::Stitcher.new(deduplicate: false)
+----
+
+== 65,535 glyph cap
+
+OpenType `maxp.numGlyphs` is uint16 — no format (TTF, CFF1, or CFF2)
+can hold more than 65,535 glyphs in a single font. The Stitcher
+enforces this:
+
+* `Stitcher::GlyphLimit.check!(count, format:)` raises
+  `GlyphLimitExceededError` when a single subfont would exceed the cap.
+* The only path to >65,535 glyphs is a TTC/OTC collection — each
+  subfont is its own 65,535-space.
+
+== CBDT/CBLC passthrough (color emoji)
+
+Sources that contain CBDT/CBLC tables (e.g. NotoColorEmoji) can be
+used as Stitcher sources. The bitmap data is propagated byte-for-byte
+into the output:
+
+[source,ruby]
+----
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:text,  Fontisan::FontLoader.load("NotoSans.ttf"))
+stitcher.add_source(:emoji, Fontisan::FontLoader.load("NotoColorEmoji.ttf"))
+
+stitcher.include_notdef(from: :text,  into: :main)
+stitcher.include_range(0x41..0x5A,    from: :text,  into: :main)
+stitcher.include_range(0x1F600..0x1F64F, from: :emoji, into: :main)
+
+stitcher.write_to("out.ttf", format: :ttf, subfont: :main)
+# → out.ttf has glyf + CBDT + CBLC, emoji renders correctly
+----
+
+Constraints:
+
+* Only ONE CBDT source per Stitcher. Multiple CBDT sources raise
+  `Fontisan::MultipleCbdtSourcesError`.
+* The CBDT source is processed first (GIDs 0..N-1) so the CBLC's GID
+  references remain valid in the output.
+
+== CLI
+
+[source,bash]
+----
+fontisan stitch \
+  --source latin=NotoSans.ttf \
+  --source cjk=FSung-m.ttf \
+  --include-range latin=0x41-0x5A \
+  --include-range cjk=0x4E00-0x9FFF \
+  --notdef-from latin \
+  --output stitched.ttf
+----
+
+== See also
+
+* link:UFO_COMPILATION.adoc[UFO Compilation Guide] — TTF/OTF/CFF2 compilers
+- link:COLLECTION_VALIDATION.adoc[Collection Validation Guide]
+- link:SVG_TO_GLYF.adoc[SVG to Glyph Guide] — turn chart SVGs into
+  Stitcher sources