fontisan 0.4.10 → 0.4.12

data/docs/STITCHER_GUIDE.adoc

@@ -21,6 +21,13 @@ There are no defaults and no after-the-fact splitting.
 
 | `add_source(label, font)` | Register a source font under a Symbol label
 
+| `add_source(label, font, remap:)` | Register a source with a
+  `{src_codepoint => target_codepoint}` remap. Useful for donor
+  fonts whose glyphs live at non-canonical codepoints (PUA, ASCII-
+  mapped pre-Unicode fonts). Source codepoints not in the remap
+  are hidden — the donor's other coverage (often ASCII/PUA noise)
+  does not leak into the output.
+
 | `include_range(range, from:, into:)` | Add codepoint range from `from` into `into`
 
 | `include_codepoints(cps, from:, into:)` | Add an explicit Array of codepoints
@@ -81,6 +88,37 @@ Each subfont is compiled independently, then packed by
 (head, name, OS/2, ...) are stored once and referenced from each
 subfont's offset table.
 
+== Donor remap (non-canonical codepoints)
+
+Some donor fonts ship glyphs at codepoints that don't match the
+canonical Unicode assignment — a keyboard-mapped font whose letters
+live at ASCII slots, or a PUA-allocated pre-Unicode font. Pass a
+`remap:` hash to `add_source` to expose those glyphs at their
+canonical targets without mutating the donor's cmap:
+
+[source,ruby]
+----
+donor = Fontisan::FontLoader.load("TolongSikiMappedToASCII.ttf")
+
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:tolong_siki, donor, remap: {
+                      0x41 => 0x11DB0, # ASCII A → Tolong Siki KA
+                      0x42 => 0x11DB1, # ASCII B → Tolong Siki NGA
+                      # ...
+                    })
+stitcher.include_codepoints((0x11DB0..0x11DC0).to_a,
+                            from: :tolong_siki, into: :tolong)
+----
+
+With a remap set, the source answers `gid_for_codepoint(target)`
+by translating through the inverse remap to the donor's source
+codepoint. Source codepoints not in the remap are hidden — only
+remapped coverage is exposed.
+
+The donor's cmap is never mutated. `remap:` is a translation layer
+at the source's API boundary; multiple sources on the same
+Stitcher can have different remaps (or none at all).
+
 `write_collection` returns a `Stitcher::CollectionResult` Struct with
 the output `path`, total `bytes`, and one `Stitcher::SubfontStats`
 per declared subfont (`name`, `glyph_count`, `codepoint_count`). Stats
@@ -188,13 +226,69 @@ A `Blueprint` is a `Struct.new(:partitions, keyword_init: true)`;
 `Blueprint#apply_to(stitcher)` calls `apply_to` on each partition in
 order and returns the list of declared subfont names.
 
-=== Future: ByBlock, ByScript
+=== ByBlock — partition by Unicode Blocks.txt
+
+`PartitionStrategy::ByBlock` partitions codepoints by their Unicode
+block. Each non-empty block becomes one partition. The full Unicode
+16.0 block list (~340 entries covering BMP, SMP, SIP, TIP, SSP) is
+inlined as `ByBlock::BLOCKS` so the partitioner is self-contained
+(no external data file). Codepoints in unassigned planes fall into
+`:block_other`.
+
+[source,ruby]
+----
+bp = Fontisan::Stitcher::PartitionStrategy::ByBlock.new
+blueprint = bp.call(cp_map)
+blueprint.names  # => [:block_basic_latin, :block_cjk_unified_ideographs, ...]
+----
+
+Every block is treated as atomic — if a single block alone exceeds
+`cap`, ByBlock raises `PartitionCapExceededError` (callers must
+either use ByPlane with carve-outs or implement a custom
+partitioner).
+
+=== ByScript — partition by Unicode script property
+
+`PartitionStrategy::ByScript` partitions codepoints by Unicode
+script (Latin, Greek, Cyrillic, Han, Hangul, etc.). Derived from
+`ByBlock::BLOCKS` via a `SCRIPT_OF_BLOCK` map — keeps the data DRY.
+
+Scripts that overflow `cap` are chunked with alphabetic suffixes
+matching ByPlane's sub-split convention (e.g. `:script_han`,
+`:script_han_a`, `:script_han_b`). Common and Inherited scripts
+get their own buckets — useful for separating shared punctuation
+and combining marks.
+
+[source,ruby]
+----
+sp = Fontisan::Stitcher::PartitionStrategy::ByScript.new
+blueprint = sp.call(cp_map)
+blueprint.names  # => [:script_common, :script_latin, :script_han, ...]
+----
+
+=== Choosing a strategy
+
+|===
+| Strategy | When to use
+
+| `ByPlane`
+| CJK-heavy fonts that need to respect the 65,535-glyph cap per
+  plane. Sub-splits only the SIP CJK extensions and the BMP
+  carve-out blocks.
+
+| `ByBlock`
+| Fonts that span many small Unicode blocks where each block
+  should land in its own subfont (e.g. for selective subsetting
+  per block). Each block is atomic.
+
+| `ByScript`
+| Web font delivery where each subfont should cover one script
+  (Latin-only file, Greek-only file, etc.). Chunks large scripts
+  (Han) when they overflow the cap.
+|===
 
-ByBlock (Unicode Blocks.txt, ~350 entries) and ByScript (Scripts.txt)
-are tracked as a follow-up. The framework is already open for them:
-add `by_block.rb` / `by_script.rb` under
-`lib/fontisan/stitcher/partition_strategy/` and an autoload entry in
-`partition_strategy.rb`.
+All three autoload from `lib/fontisan/stitcher/partition_strategy/`.
+Adding a new strategy = new file + one autoload entry (OCP).
 
 == Per-subfont metadata (Ufo::Info.for_subfont)
 

data/docs/TTX.adoc

@@ -0,0 +1,176 @@
+= TTX (FontTools XML) Support
+
+fontisan can read and write the TTX format — the human-readable
+XML representation of OpenType fonts defined by Adobe/FontTools'.
+`ttx` tool. TTX is the standard interchange format for OpenType
+table data: every binary table has a corresponding XML element,
+and round-tripping TTX ↔ binary preserves the table contents.
+
+== Why TTX
+
+* **Diff-friendly**: TTX is text, so changes to a font's tables can
+  be reviewed in version control.
+* **Edit-friendly**: you can hand-edit table values without writing
+  binary parsers.
+* **Tool interchange**: any tool that understands TTX (fontTools,
+  AFDKO's `ttx`, several IDE plugins) can read fontisan's output
+  and vice versa.
+
+== What fontisan supports
+
+[cols="1,3", options="header"]
+|===
+| Capability | Notes
+
+| Read `.ttx` (parse XML → typed tables)
+| Every standard table that fontisan parses as binary also has a
+  TTX parser entry. Unknown tables fall through to a binary-blob
+  representation.
+
+| Write `.ttx` (typed tables → XML)
+| Same coverage as the read path. Each table knows how to render
+  itself as TTX.
+
+| CLI `fontisan export FONT --format ttx`
+| Dumps every table or a subset via `--tables`.
+
+| CLI `fontisan info FONT` (auto-detect)
+| Auto-detects `.ttx` files alongside binary formats. No
+  `--format` flag needed.
+
+| Per-table type mapping (lib/fontisan/models/ttx/tables/*.rb)
+| `head`, `hhea`, `maxp`, `name`, `OS/2`, `post` have typed
+  representations; everything else is `BinaryTable` (raw bytes).
+|===
+
+== CLI usage
+
+[source,bash]
+----
+# Dump the entire font as TTX
+fontisan export MyFont.ttf --format ttx --output MyFont.ttx
+
+# Dump just the head + name tables
+fontisan export MyFont.ttf --format ttx --tables head name --output subset.ttx
+
+# Read a TTX file (auto-detected)
+fontisan info MyFont.ttx
+fontisan validate MyFont.ttx
+----
+
+== Ruby API
+
+=== Generate TTX from a loaded font
+
+[source,ruby]
+----
+require "fontisan"
+
+font = Fontisan::FontLoader.load("MyFont.ttf")
+generator = Fontisan::Export::TtxGenerator.new(font, "MyFont.ttf")
+ttx_xml = generator.generate
+File.write("MyFont.ttx", ttx_xml)
+----
+
+=== Parse TTX into typed tables
+
+[source,ruby]
+----
+require "fontisan/export"
+
+ttx_xml = File.read("MyFont.ttx")
+parser = Fontisan::Export::TtxParser.new
+tt_font = parser.parse(ttx_xml)
+
+puts "sfnt version: #{tt_font.sfnt_version}"
+puts "tables: #{tt_font.tables.keys.join(', ')}"
+
+head = tt_font.tables["head"]
+puts "units per em: #{head.units_per_em}" if head
+----
+
+=== Round-trip
+
+Read TTX → modify → write TTX:
+
+[source,ruby]
+----
+parser = Fontisan::Export::TtxParser.new
+tt_font = parser.parse(File.read("MyFont.ttx"))
+
+# Bump units-per-em (caution: this rescales visually)
+tt_font.tables["head"].units_per_em = 2048
+
+# Re-emit as TTX
+generator = Fontisan::Export::TtxGenerator.from_tt_font(tt_font)
+File.write("MyFont-edited.ttx", generator.generate)
+----
+
+== Typed table coverage
+
+fontisan's TTX layer is a parallel hierarchy to the binary
+`Tables::*` classes. Each TTX table class lives under
+`Fontisan::Models::Ttx::Tables`:
+
+[cols="1,1", options="header"]
+|===
+| Binary table | TTX class
+
+| `head`
+| `Models::Ttx::Tables::HeadTable`
+
+| `hhea`
+| `Models::Ttx::Tables::HheaTable`
+
+| `maxp`
+| `Models::Ttx::Tables::MaxpTable`
+
+| `name`
+| `Models::Ttx::Tables::NameTable`
+
+| `OS/2`
+| `Models::Ttx::Tables::Os2Table`
+
+| `post`
+| `Models::Ttx::Tables::PostTable`
+
+| (any other)
+| `Models::Ttx::Tables::BinaryTable` — raw bytes, no typed
+  interpretation
+|===
+
+Adding a new typed TTX representation = one file under
+`models/ttx/tables/` + one entry in the parser dispatch table.
+
+== Compatibility with fontTools `ttx`
+
+fontisan's TTX output is byte-compatible with fontTools `ttx`
+output for the typed tables. The XML element names, attribute
+names, and value formats match the fontTools schema.
+
+The `BinaryTable` representation differs slightly: fontTools
+emits a hex-dumped `<hexdata>` block for tables it doesn't
+understand; fontisan emits the same format.
+
+== Related formats
+
+fontisan also exports YAML and JSON via the same `fontisan export`
+command — useful for scripting and AI/automation pipelines where
+XML's verbosity is a drawback:
+
+[source,bash]
+----
+fontisan export MyFont.ttf --format yaml --output MyFont.yaml
+fontisan export MyFont.ttf --format json --output MyFont.json
+----
+
+== See also
+
+* link:UFO_COMPILATION.adoc[UFO Compilation Guide] — UFO is a
+  richer source format than TTX (full glyph outlines + naming +
+  features); use TTX for binary-table inspection, UFO for source
+  editing.
+* link:AFDKO_MIGRATION.adoc[AFDKO Migration Guide] — fontisan
+  replaces AFDKO's `ttx` command.
+* link:FEATURE_PARITY.adoc[Feature Parity] — every external tool
+  fontisan replaces.

data/docs/UFO_COMPILATION.adoc

@@ -110,10 +110,288 @@ ufo = Fontisan::Ufo::Convert::FromBinData.convert(ttf)
 Fontisan::Ufo::Writer.new(ufo).write("MyFont.ufo")
 ----
 
+== Conversion wrappers (Phase 3)
+
+For every binary format fontisan can write, there's a UFO → that
+format wrapper under `Ufo::Convert`. They split into two flavors:
+
+1-step wrappers (compile + write directly): `ToTtf`, `ToOtf`,
+`ToOtf2`.
+
+2-step wrappers (compile to TTF/OTF in a tmpfile, then encode):
+`ToWoff`, `ToWoff2`, `ToDfont`, `ToTtc`, `ToOtc`, `ToPfb`,
+`ToPfa`.
+
+The 2-step chain looks like:
+
+....
+UFO → Compile::*Compiler → tmpfile → FontLoader.load →
+       WoffWriter / Woff2Encoder / DfontBuilder /
+       Collection::Builder / Type1::PFB/PFAGenerator → output
+....
+
+The tmpfile is auto-cleaned (`Dir.mktmpdir`); the original UFO is
+never mutated.
+
+Use the unified dispatcher to pick a format by symbol:
+
+[source,ruby]
+----
+require "fontisan"
+
+ufo = Fontisan::Ufo::Font.open("MyFont.ufo")
+
+# 1-step
+Fontisan::Ufo::Convert.convert(ufo, to: :ttf, output_path: "MyFont.ttf")
+Fontisan::Ufo::Convert.convert(ufo, to: :otf, output_path: "MyFont.otf")
+
+# 2-step
+Fontisan::Ufo::Convert.convert(ufo, to: :woff2, output_path: "MyFont.woff2")
+Fontisan::Ufo::Convert.convert(ufo, to: :pfb,    output_path: "MyFont.pfb")
+----
+
+Format keys: `:ttf`, `:otf`, `:otf2`, `:woff`, `:woff2`, `:dfont`,
+`:ttc`, `:otc`, `:pfb`, `:pfa`. Unknown keys raise `ArgumentError`.
+
+For per-format options (zlib level, brotli quality, etc.) call the
+wrapper module directly — options forward through:
+
+[source,ruby]
+----
+Fontisan::Ufo::Convert::ToWoff2.convert(ufo,
+  output_path: "MyFont.woff2",
+  compiler: :otf,             # intermediate format
+  brotli_quality: 11,         # passed to Woff2Encoder
+  transform_tables: true)
+----
+
+== Glyph-processing filters (Phase 2)
+
+Filters sit between the UFO model and the binary compilers. Each is
+a stateless module under `Ufo::Compile::Filters` with a `.run(glyphs,
+**opts)` entry that mutates the glyph list in place. They're
+registered in `Filters::REGISTRY` so the compiler (or any caller)
+can apply them by symbol:
+
+[source,ruby]
+----
+glyphs = ufo.layers.default_layer.glyphs.values
+Fontisan::Ufo::Compile::Filters.apply(
+  %i[cubic_to_quadratic reverse_contour_direction sort_contours],
+  glyphs
+)
+----
+
+Available filters:
+
+[cols="1,3", options="header"]
+|===
+| Filter | What it does
+
+| `cubic_to_quadratic`
+| Convert cubic Bezier curves to quadratic (TrueType only supports
+  quadratic; UFO sources typically use cubic).
+
+| `reverse_contour_direction`
+| Reverse point order in every contour (TrueType wants clockwise
+  outer winding; UFO is PostScript counter-clockwise).
+
+| `decompose_components`
+| Replace composite-glyph components with their base glyph's
+  contours.
+
+| `flatten_components`
+| Collapse nested component chains (A→B→C becomes A→C).
+
+| `transformations`
+| Apply a 2×3 affine matrix to every glyph's contours + components
+  (mirroring, slant, scaling, custom offsets).
+
+| `sort_contours`
+| Rotate each contour to start with an on-curve point and sort
+  contours within each glyph by Y (descending) for hinting
+  compatibility.
+
+| `propagate_anchors`
+| Copy anchors from base glyphs to composite glyphs (transformed by
+  the component matrix) so the GPOS mark feature writer can find
+  them on composites.
+|===
+
+Adding a new filter = one file under `compile/filters/` + one entry
+in `REGISTRY`. No edits to other filters required (OCP).
+
+== Feature writers (Phase 2)
+
+Feature writers extract GSUB/GPOS feature data from a UFO source
+into structured form for the table builders to encode. Each writer
+extends `FeatureWriters::Base` with a `#write` method that returns
+either a `FeatureOutput` value object or `nil` (when the UFO has
+no data for the feature).
+
+[source,ruby]
+----
+require "fontisan/ufo/compile/feature_writers"
+
+font = Fontisan::Ufo::Font.open("MyFont.ufo")
+Fontisan::Ufo::Compile::FeatureWriters::DEFAULT_WRITERS.each do |writer_cls|
+  output = writer_cls.new(font).write
+  next unless output
+
+  puts "#{output.table_tag} / #{output.feature_tag} (lookup #{output.lookup_type})"
+end
+----
+
+Available writers:
+
+[cols="1,1,3", options="header"]
+|===
+| Writer | GPOS / GSUB | What it emits
+
+| `FeatureWriters::Kern`
+| GPOS lookup 2 (`kern`)
+| PairPos kerning pairs from `font.kerning` (parsed from
+  `kerning.plist`).
+
+| `FeatureWriters::Kern2`
+| GPOS lookup 2 (`kern`, format 2)
+| Same pair data as Kern, tagged for the extended PairPos format
+  (device tables, cross-stream values). Use when you need
+  sub-pixel kerning.
+
+| `FeatureWriters::Gdef`
+| GDEF
+| GlyphClassDef — classifies every glyph as base/ligature/mark/
+  spacing. Prefers `public.openTypeCategory` lib entry; falls
+  back to heuristic (mark anchors, `.liga` suffix).
+
+| `FeatureWriters::Mark`
+| GPOS lookup 4 (`mark`)
+| MarkToBase attachment. Pairs every glyph with a `_<name>`
+  anchor (mark) against every glyph with the matching `<name>`
+  anchor (base).
+
+| `FeatureWriters::Mkmk`
+| GPOS lookup 6 (`mkmk`)
+| MarkToMark attachment. Same convention as Mark but pairs marks
+  with other marks. Anchors are `_<name>mkmk` (attach-from) ↔
+  `<name>mkmk` (attach-to).
+
+| `FeatureWriters::Curs`
+| GPOS lookup 3 (`curs`)
+| Cursive attachment. Emits entry/exit anchor positions for
+  joining-script glyphs.
+|===
+
+`FeatureWriters::DEFAULT_WRITERS = [Gdef, Kern, Mark, Mkmk, Curs]`.
+The compiler runs all by default; each returns `nil` when the UFO
+has no data for its feature, so it's safe to always run them all.
+
+Adding a new writer = one file under `compile/feature_writers/` +
+one entry in `DEFAULT_WRITERS`. No edits to other writers required
+(OCP).
+
+Prerequisite for Mark / Mkmk / Curs: run
+`Filters::PropagateAnchors` first so composite glyphs carry their
+inherited anchors.
+
+=== Usage examples
+
+==== Kern (pair kerning)
+
+Extract kerning pairs from a UFO's `kerning.plist`:
+
+[source,ruby]
+----
+font = Fontisan::Ufo::Font.open("MyFont.ufo")
+out = Fontisan::Ufo::Compile::FeatureWriters::Kern.new(font).write
+
+out.data[:pairs].each do |pair|
+  puts "#{pair[:left]} + #{pair[:right]} = #{pair[:value]}"
+end
+# A + V = -80.0
+# A + W = -60.0
+# ...
+----
+
+==== Gdef (glyph classification)
+
+Classify every glyph for GDEF:
+
+[source,ruby]
+----
+out = Fontisan::Ufo::Compile::FeatureWriters::Gdef.new(font).write
+out.data[:classes].each { |name, cls| puts "#{name}: #{cls}" }
+# A: 1 (base)
+# f_f_i.liga: 2 (ligature)
+# acutecomb: 3 (mark)
+# ...
+----
+
+==== Mark (mark-to-base attachment)
+
+Pair diacritical marks with base glyphs:
+
+[source,ruby]
+----
+out = Fontisan::Ufo::Compile::FeatureWriters::Mark.new(font).write
+out.data[:attachments]["top"][:marks]   # => {"acutecomb" => [100, 600], ...}
+out.data[:attachments]["top"][:bases]   # => {"A" => [100, 700], "B" => [90, 700], ...}
+----
+
+==== Mkmk (mark-to-mark attachment)
+
+Stack marks above each other:
+
+[source,ruby]
+----
+out = Fontisan::Ufo::Compile::FeatureWriters::Mkmk.new(font).write
+out.data[:attachments]["top"][:marks]       # => {"acutecomb" => [100, 650]}
+out.data[:attachments]["top"][:base_marks]  # => {"dieresiscomb" => [100, 700]}
+----
+
+==== Curs (cursive joining)
+
+Emit entry/exit anchors for Arabic-script glyphs:
+
+[source,ruby]
+----
+out = Fontisan::Ufo::Compile::FeatureWriters::Curs.new(font).write
+out.data[:attachments]["alef"]  # => {entry: [0, 100], exit: [100, 100]}
+out.data[:attachments"]["beh"]  # => {entry: [50, 50], exit: nil}
+----
+
+== CLI
+
+`fontisan ufo` exposes the four common operations:
+
+[source,bash]
+----
+# Compile a UFO to a binary font
+fontisan ufo build MyFont.ufo --output MyFont.ttf [--to otf|otf2]
+
+# Convert in either direction (UFO ↔ binary)
+fontisan ufo convert MyFont.ufo MyFont.woff2
+fontisan ufo convert MyFont.ttf  MyFont.ufo
+
+# Structural checks (no .notdef, no family name, etc.)
+fontisan ufo validate MyFont.ufo
+
+# Render one glyph as a standalone SVG
+fontisan ufo extract MyFont.ufo A A.svg
+----
+
+The `build` and `convert` commands route through the
+`Ufo::Convert.convert` dispatcher, so adding a new format = one
+registry entry — no CLI edits.
+
 == See also
 
+* link:AFDKO_MIGRATION.adoc[AFDKO Migration Guide] — switching from
+  `makeotf` / `otf2ttf` / `ttx` to fontisan's UFO pipeline.
 * link:CFF2_SUPPORT.adoc[CFF2 Support Guide] — variable-font blend
-  operators, FDSelect, subroutines, VariationStore
+  operators, FDSelect, subroutines, VariationStore.
 * link:VARIABLE_FONT_OPERATIONS.adoc[Variable Font Operations] —
-  reading and modifying existing variable fonts
-- link:STITCHER_GUIDE.adoc[Stitcher Guide] — multi-source assembly
+  reading and modifying existing variable fonts.
+* link:STITCHER_GUIDE.adoc[Stitcher Guide] — multi-source assembly.
+