fontisan 0.4.11 → 0.4.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ed3f50509fb7f223b2cdcfdf7e59345e83b5ca2d11b2a0806574651687c4582
-  data.tar.gz: ccb6cabe8c99dfcc060acc7f46d26efd9961b5384365ab404552dad539dc4555
+  metadata.gz: e97f99deb241e5abd1bbdaeb27849efb3a4597bf2139fc8a1fa815fcccbfdfcb
+  data.tar.gz: ced71eac0e00e479581c5460e33672aa80ded30cd40cb590b5a09621c5441290
 SHA512:
-  metadata.gz: b977d4f9ac972020514daca43a14917784c713258f73223597c8a48dd2b32fcf3ccb9adbe2bd343db7ac43e63eaba8943a883580ec3c7bb7dec23f6a0f1e1fe9
-  data.tar.gz: 5c17de9dc3c60f44e472e94c19a1ca33435805ed81f261cc357dfcfd6d197f3109531ae8ad4b3a842e52f4f04de19501c0e860793212b87e874b63f01d99d8f3
+  metadata.gz: cc72fc9f58560fddf2440ecead8a54060a06a6da38ac3de2212d893cb3dbb2dea88649c82c30ff8fb10d25389058a63770d4309e414856f031ab3d88659f4150
+  data.tar.gz: bac0c91aa712516256d2ae7fb7ccee7dd31fe1549ace5bb533ea9d2b27b7087da4b0b200412794b3677b44c43bae79c87cbcaa849db3f6d993d00dac91a1e3a3

data/README.adoc

@@ -15,7 +15,9 @@ and Adobe Type 1 fonts (OTF, TTF, OTC, TTC, dfont, PFB, PFA).
 The gem provides both a Ruby library API and a command-line interface, with
 structured output formats (YAML, JSON, text) via lutaml-model.
 
-Fontisan is designed to replace the following tools:
+Fontisan is designed to replace the following tools (see
+link:docs/FEATURE_PARITY.adoc[Feature Parity] for the full list and
+per-tool coverage):
 
 * `otfinfo` from http://www.lcdf.org/type/[LCDF Typetools]. Fontisan supports
 all features provided by `otfinfo`, including extraction of font metadata,
@@ -30,6 +32,26 @@ validation, format conversion, and collection creation. See
 link:docs/EXTRACT_TTC_MIGRATION.md[extract_ttc Migration Guide] for detailed
 command mappings and usage examples.
 
+* **Adobe AFDKO** — `makeotf`, `otf2ttf`, `ttx`, `mergeFonts`,
+  `checkOutlinesUFO`, `rotateFont`. See
+  link:docs/AFDKO_MIGRATION.adoc[AFDKO Migration Guide].
+
+* **Python fontTools + ufoLib2 + ufo2ft** — UFO model layer, UFO
+  compile pipeline (TTF/OTF/CFF2 + variable), glyph filters (8/8),
+  feature writers (GDEF, kern, mark, mkmk, curs), `pyftsubset`,
+  `pyftmerge`, `varLib`. See link:docs/UFO_COMPILATION.adoc[UFO Compilation Guide].
+
+* **`ttx` (TTX format)** — full read/write of the FontTools XML
+  format. See link:docs/TTX.adoc[TTX Support].
+
+* **Google `woff2_compress` / `woff2_decompress`** — WOFF and
+  WOFF2 compression/decompression in pure Ruby. See
+  link:docs/WOFF_WOFF2_FORMATS.adoc[WOFF/WOFF2 Formats Guide].
+
+* **Type 1 utilities** (`t1disasm`, `t1asm`, `t1embed`, `pfm2afm`)
+  — full PFB/PFA parse/generate, eexec decryption, PFM↔AFM
+  round-trip. See link:docs/TYPE1_FONTS.adoc[Type 1 Fonts Guide].
+
 
 == Installation
 
@@ -60,11 +82,15 @@ 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])
+* UFO → all binary formats via the `Ufo::Convert` dispatcher: TTF, OTF, OTF2, WOFF, WOFF2, dfont, TTC, OTC, PFB, PFA
+* UFO feature writers: GDEF glyph classification, GPOS kern/mark/mkmk/curs (see link:docs/UFO_COMPILATION.adoc[UFO Compilation Guide — Filters + Feature Writers])
+* Glyph-processing filters: cubic_to_quadratic, decompose_components, flatten_components, reverse_contour_direction, transformations, sort_contours, propagate_anchors, remove_overlaps
 * 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
+* AFDKO migration: drop-in replacement for `makeotf`, `otf2ttf`, `ttx`, `mergeFonts`, `checkOutlinesUFO` (see link:docs/AFDKO_MIGRATION.adoc[AFDKO Migration Guide])
 
 Color fonts and collections::
 * Color font table builders: COLR v0, CPAL, SVG table, sbix, CBDT/CBLC (see link:docs/COLOR_FONTS.adoc[Color Fonts Guide])

data/docs/AFDKO_MIGRATION.adoc

@@ -0,0 +1,175 @@
+= AFDKO Migration Guide
+
+This guide maps commands and concepts from Adobe Font Development
+Kit for OpenType (AFDKO) — `makeotf`, `otf2ttf`, `ttx`, `mergeFonts`,
+`rotateFont` — to their pure-Ruby equivalents in fontisan.
+
+fontisan's UFO pipeline replaces every AFDKO command for the
+compile/convert/validate workflows. No external toolchain required.
+
+== Command map
+
+[cols="1,1,3", options="header"]
+|===
+| AFDKO | fontisan | Notes
+
+| `makeotf -f font.ufo -o font.otf`
+| `fontisan ufo build font.ufo --output font.otf --to otf`
+| CFF1 output by default; pass `--to otf2` for CFF2 (variable fonts).
+
+| `makeotf -f font.ufo -o font.ttf`
+| `fontisan ufo build font.ufo --output font.ttf --to ttf`
+| TrueType (glyf) output. `cubic_to_quadratic` and
+  `reverse_contour_direction` filters run automatically.
+
+| `ttx font.ttf`
+| `fontisan ufo convert font.ttf font.ufo`
+| `ttx` produces XML; fontisan produces a typed UFO source directory.
+
+| `otf2ttf font.otf`
+| `fontisan convert font.otf font.ttf`
+| Outline conversion (CFF → glyf) is handled by the
+  `OutlineConverter` strategy; no Python required.
+
+| `mergeFonts out.ufo a.ufo b.ufo`
+| Use `Fontisan::Stitcher` (see link:STITCHER_GUIDE.adoc[Stitcher Guide])
+| Stitcher is more flexible — supports per-source codepoint remaps,
+  glyph-cap partitioning, and deduplication.
+
+| `rotateFont` (font info updates)
+| Edit `Fontisan::Ufo::Info` directly
+| fontisan exposes the full UFO model in Ruby.
+
+| `checkOutlinesUFO font.ufo`
+| `fontisan ufo validate font.ufo`
+| Plus the link:COLLECTION_VALIDATION.adoc[collection validator] for TTC/OTC.
+
+| (no AFDKO equivalent)
+| `fontisan ufo extract font.ufo A A.svg`
+| Per-glyph standalone SVG export — new in fontisan.
+|===
+
+== Compile-time options
+
+AFDKO uses a `font.ufo/lib.plist` `com.github.fonttools` manifest
+plus a `FontMenuNameDB` / `GlyphOrderAndAliasDB` file pair. fontisan
+takes those inline:
+
+[source,ruby]
+----
+ufo = Fontisan::Ufo::Font.open("font.ufo")
+ufo.info.family_name = "MyFont"
+ufo.info.postscript_full_name = "MyFont-Regular"
+
+# Apply a uniform scale before compile (AFDKO's -sh / -sz options)
+Fontisan::Ufo::Compile::Filters.apply(
+  [:transformations],
+  ufo.layers.default_layer.glyphs.values,
+  matrix: [1.1, 0, 0, 1.1, 0, 0] # 110% scale
+)
+
+Fontisan::Ufo::Convert.convert(ufo, to: :otf, output_path: "font.otf")
+----
+
+== Variable fonts
+
+AFDKO's `makeotf -f default.ufo -i instances/...` master-instance
+model maps to fontisan's `Ufo::Compile::VariableTtf` /
+`VariableOtf` compilers, which read the UFO's `fvar` + `gvar` +
+designspace data directly.
+
+[source,ruby]
+----
+ufo = Fontisan::Ufo::Font.open("MyVariable.ufo")
+Fontisan::Ufo::Compile::VariableTtf.new(ufo).compile(output_path: "MyVariable.ttf")
+----
+
+For OTF (CFF2) variable fonts, use `Compile::VariableOtf` or pass
+`to: :otf2` through the dispatcher.
+
+== Filter pipelines
+
+AFDKO has no first-class filter pipeline — you'd shell out to
+Python fontTools `ufo2ft.filters.*`. fontisan ships the equivalent
+filters in pure Ruby:
+
+[source,ruby]
+----
+glyphs = ufo.layers.default_layer.glyphs.values
+
+Fontisan::Ufo::Compile::Filters.apply(
+  %i[
+    decompose_components
+    propagate_anchors
+    cubic_to_quadratic
+    reverse_contour_direction
+    sort_contours
+  ],
+  glyphs
+)
+----
+
+Run them in this order: decompose first (so subsequent filters see
+only simple glyphs), then propagate anchors (uses base glyphs'
+anchors), then the TrueType-required conversions, finally sort.
+
+== Output formats at a glance
+
+fontisan can produce every format AFDKO can, plus a few AFDKO
+cannot:
+
+[cols="1,1", options="header"]
+|===
+| Format | Command
+
+| TrueType (`.ttf`)
+| `fontisan ufo build f.ufo --output f.ttf`
+
+| OpenType CFF1 (`.otf`)
+| `fontisan ufo build f.ufo --output f.otf --to otf`
+
+| OpenType CFF2 (`.otf`, variable)
+| `fontisan ufo build f.ufo --output f.otf --to otf2`
+
+| WOFF (compressed TTF/OTF)
+| `fontisan ufo convert f.ufo f.woff`
+
+| WOFF2 (Brotli-compressed)
+| `fontisan ufo convert f.ufo f.woff2`
+
+| Mac dfont (resource fork)
+| `fontisan ufo convert f.ufo f.dfont`
+
+| TrueType Collection (`.ttc`)
+| `fontisan ufo convert f.ufo f.ttc`
+
+| OpenType Collection (`.otc`)
+| `fontisan ufo convert f.ufo f.otc`
+
+| PostScript Type 1 Binary (`.pfb`)
+| `fontisan ufo convert f.ufo f.pfb`
+
+| PostScript Type 1 ASCII (`.pfa`)
+| `fontisan ufo convert f.ufo f.pfa`
+|===
+
+== Why migrate
+
+* **No AFDKO install** — fontisan is a Ruby gem; no separate
+  toolchain to license, install, or version-pin.
+* **No Python dependency** — fontisan is pure Ruby. Eliminates the
+  Python fontTools + ufo2ft + ufoLib2 stack from your build.
+* **Single source of truth** — fontisan reads, writes, and round-trips
+  every format. No format-specific tools.
+* **Programmatic API** — every CLI command has a Ruby equivalent
+  under `Fontisan::Ufo::*`. Scriptable in ways AFDKO shells cannot
+  match.
+
+== See also
+
+* link:UFO_COMPILATION.adoc[UFO Compilation Guide] — full reference
+  for the compile / convert / filter / CLI surface.
+* link:STITCHER_GUIDE.adoc[Stitcher Guide] — replaces `mergeFonts`
+  with codepoint remaps, partition strategies, and dedup.
+* link:CFF2_SUPPORT.adoc[CFF2 Support] — variable-font blend
+  operators.

data/docs/FEATURE_PARITY.adoc

@@ -0,0 +1,263 @@
+= Feature Parity — Tools fontisan Replaces
+
+fontisan is a pure-Ruby replacement for several established font
+toolchains. This page lists every external tool fontisan can
+substitute for, with notes on coverage and migration paths.
+
+== Adobe Font Development Kit for OpenType (AFDKO)
+
+The AFDKO ships a suite of command-line tools for font
+development. fontisan replaces every one in pure Ruby.
+
+[cols="1,1,3", options="header"]
+|===
+| AFDKO | fontisan | Notes
+
+| `makeotf -f font.ufo -o font.otf`
+| `fontisan ufo build font.ufo --output font.otf --to otf`
+| CFF1 by default; `--to otf2` for CFF2 (variable fonts).
+
+| `makeotf -f font.ufo -o font.ttf`
+| `fontisan ufo build font.ufo --output font.ttf --to ttf`
+| TrueType (glyf). `cubic_to_quadratic` +
+  `reverse_contour_direction` filters run automatically.
+
+| `ttx font.ttf` / `ttx font.ttx`
+| `fontisan export font.ttf --format ttx` / `fontisan info font.ttx`
+| See link:TTX.adoc[TTX Support]. Byte-compatible output for
+  typed tables.
+
+| `otf2ttf font.otf`
+| `fontisan convert font.otf font.ttf`
+| Outline conversion (CFF → glyf) via `OutlineConverter`.
+
+| `mergeFonts out.ufo a.ufo b.ufo`
+| `Fontisan::Stitcher` (see link:STITCHER_GUIDE.adoc[Stitcher Guide])
+| More flexible: per-source codepoint remaps, partition
+  strategies (Plane/Block/Script), glyph-cap enforcement,
+  deduplication.
+
+| `rotateFont` (font-info updates)
+| Edit `Fontisan::Ufo::Info` directly
+| fontisan exposes the full UFO model in Ruby.
+
+| `checkOutlinesUFO font.ufo`
+| `fontisan ufo validate font.ufo`
+| Plus the link:COLLECTION_VALIDATION.adoc[collection validator]
+  for TTC/OTC.
+
+| (no AFDKO equivalent)
+| `fontisan ufo extract font.ufo A A.svg`
+| Per-glyph standalone SVG export.
+|===
+
+link:AFDKO_MIGRATION.adoc[AFDKO Migration Guide] → full command
+reference and pipeline examples.
+
+== LCDF Typetools (`otfinfo`)
+
+`otfinfo` from http://www.lcdf.org/type/[LCDF Typetools] is the
+canonical font-metadata display tool. fontisan replaces it
+entirely.
+
+[cols="1,1", options="header"]
+|===
+| otfinfo | fontisan
+
+| `otfinfo -i font.otf`
+| `fontisan info font.otf`
+
+| `otfinfo --brief font.otf` (fast)
+| `fontisan info font.otf --brief` (~5× faster, metadata-only)
+
+| Per-flag queries (`--family`, `--postscript-name`, etc.)
+| `--fields` flag selects specific fields
+|===
+
+fontisan supports every field `otfinfo` produces, plus extras
+(color capabilities, variable-font detail, OpenType layout
+features). The `info` command auto-detects file format from
+magic bytes — never trusts extensions.
+
+== `extract_ttc`
+
+https://github.com/fontist/extract_ttc[extract_ttc] extracts
+fonts from a TrueType/OpenType Collection (`.ttc`/`.otc`).
+fontisan replaces it with Docker-style subcommands:
+
+[source,bash]
+----
+# extract_ttc
+extract_ttc font.ttc
+
+# fontisan
+fontisan collection ls font.ttc      # list faces
+fontisan collection info font.ttc    # per-face metadata
+fontisan collection extract font.ttc # write each face to disk
+----
+
+link:docs/EXTRACT_TTC_MIGRATION.md[extract_ttc Migration Guide] →
+full command mapping.
+
+== Python fontTools + ufoLib2 + ufo2ft
+
+fontTools is the dominant Python font library. fontisan replaces
+its core surfaces in pure Ruby:
+
+[cols="1,1,3", options="header"]
+|===
+| fontTools / ufoLib2 / ufo2ft | fontisan | Coverage
+
+| `fontTools.ttx` (TTX I/O)
+| `Fontisan::Export::TtxParser` + `TtxGenerator` (see link:TTX.adoc[TTX])
+| Typed read/write of every standard table.
+
+| `ufoLib2` (UFO model layer)
+| `Fontisan::Ufo::*` (16 model classes)
+| Substantially complete. Allotments: Info, Font, Layer, LayerSet,
+  Glyph, Contour, Point, Component, Anchor, Guideline, Image,
+  Kerning, Features, Lib, DataSet, ImageSet.
+
+| `ufo2ft.compile*` (UFO compile)
+| `Fontisan::Ufo::Compile::TtfCompiler` / `OtfCompiler` /
+  `Otf2Compiler` / `VariableTtf` / `VariableOtf`
+| Full compile pipeline. TTF, OTF (CFF1), OTF2 (CFF2), variable.
+
+| `ufo2ft.filters.*` (glyph filters)
+| `Fontisan::Ufo::Compile::Filters::*`
+| 8/8: cubic_to_quadratic, decompose_components,
+  flatten_components, reverse_contour_direction, transformations,
+  sort_contours, propagate_anchors, remove_overlaps (bbox approx).
+
+| `ufo2ft.featureWriters.*` (GSUB/GPOS writers)
+| `Fontisan::Ufo::Compile::FeatureWriters::*`
+| 6/6 commonly-needed: Kern, Kern2, Gdef, Mark, Mkmk, Curs. Each
+  returns structured data for the table builders to encode.
+
+| `fontTools.subset` (pyftsubset)
+| `Fontisan::Subset::*` + `fontisan subset` CLI
+| Profiles: PDF, web, minimal. Codepoint subset + table
+  stripping.
+
+| `fontTools.merge` (pyftmerge)
+| `Fontisan::Stitcher` (see link:STITCHER_GUIDE.adoc[Stitcher Guide])
+| More flexible than pyftmerge: explicit per-face codepoint
+  binding, deduplication, partition by plane/block/script.
+
+| `fontTools.varLib` (variable font assembly)
+| `Fontisan::Ufo::Compile::VariableTtf` / `VariableOtf` /
+  `Avar` / `Hvar` / `Mvar` / `Stat` / `Gvar` / `Fvar`
+| Full variable-font compile from UFO masters.
+|===
+
+== Type 1 font tools
+
+fontisan parses and generates Type 1 fonts (`.pfb`, `.pfa`),
+replacing several specialty tools:
+
+[cols="1,1,3", options="header"]
+|===
+| Tool | fontisan | Notes
+
+| `t1disasm` / `t1asm` (Type 1 dis/assembler)
+| `Fontisan::Type1::PfbParser` / `PFBGenerator` /
+  `PFAGenerator`
+| Round-trips PFB ↔ Type 1 charstring tokens.
+
+| `t1embed` / `t1unembed` (font embedding)
+| `Fontisan::Type1::Decryptor` + charstring layer
+| Eexec decryption + charstring de-encryption.
+
+| PFM Tools (`pfm2afm`, etc.)
+| `Fontisan::Type1::PfmParser` + `AfmGenerator`
+| Round-trip PFM ↔ AFM.
+|===
+
+link:TYPE1_FONTS.adoc[Type 1 Fonts Guide] → full reference.
+
+== WOFF / WOFF2 compress / decompress
+
+[cols="1,1,3", options="header"]
+|===
+| Tool | fontisan | Notes
+
+| Google `woff2_compress`
+| `Fontisan::Converters::WoffWriter`
+| zlib compression for WOFF.
+
+| Google `woff2_decompress`
+| `Fontisan::FontLoader.load` (auto-detects WOFF2)
+| Decompresses to in-memory TTF/OTF.
+
+| Google `woff2_compress` (Brotli)
+| `Fontisan::Converters::Woff2Encoder`
+| Brotli compression for WOFF2 with optional table transforms.
+|===
+
+link:WOFF_WOFF2_FORMATS.adoc[WOFF/WOFF2 Formats Guide] → full
+reference.
+
+== Variable font tools
+
+[cols="1,1,3", options="header"]
+|===
+| Tool | fontisan | Notes
+
+| `fontTools.varLib.instancer`
+| `Fontisan::Variation::Optimizer` + `InstantiateCommand`
+| Generates static instances from a variable font.
+
+| `fontTools.varLib.merger`
+| `Fontisan::Ufo::Compile::VariableTtf` / `VariableOtf`
+| Merges UFO masters into a variable font.
+
+| `fontTools.ttLib` variable-font table read/write
+| `Tables::Fvar`, `Tables::Gvar`, `Tables::Avar`, `Tables::Hvar`,
+  `Tables::Vvar`, `Tables::Mvar`, `Tables::Stat`
+| Full read/write for every variation table.
+|===
+
+link:VARIABLE_FONT_OPERATIONS.adoc[Variable Font Operations] →
+full reference.
+
+== Validation
+
+[cols="1,1,3", options="header"]
+|===
+| Tool | fontisan | Notes
+
+| `fontTools.fontBuilder` (validation hooks)
+| `Fontisan::Validators::*` (DSL framework)
+| Profiles: indexability, usability, production, web,
+  spec_compliance, default. Each profile = set of checks.
+
+| `fontTools.ttx` round-trip checks
+| `fontisan validate font.ttf`
+| Runs every check in the chosen profile.
+|===
+
+link:VALIDATION.adoc[Validation Guide] → full reference.
+
+== What fontisan does NOT replace
+
+For honesty:
+
+* **Glyph editing GUI** — fontisan is a library, not a font
+  editor. Use FontForge, Glyphs, RoboFont, or FontLab for visual
+  editing; use fontisan for the build/inspect/validate pipeline.
+* **Glyph drawing from scratch** — fontisan reads/writes outline
+  data but has no canvas/drawing primitives. Generate outlines in
+  an editor or programmatically via the UFO model.
+* **Bitmap font rendering** — fontisan is for font files, not
+  rasterizing text. Use HarfBuzz + a renderer for that.
+* **Heavy polygon clipping** — fontisan's `remove_overlaps`
+  filter uses a bounding-box approximation. For production-grade
+  boolean ops, preprocess in FontLab or use the `clipper` gem.
+
+== See also
+
+* link:UFO_COMPILATION.adoc[UFO Compilation Guide]
+* link:TTX.adoc[TTX Support]
+* link:STITCHER_GUIDE.adoc[Stitcher Guide]
+* link:AFDKO_MIGRATION.adoc[AFDKO Migration Guide]
+* link:EXTRACT_TTC_MIGRATION.md[extract_ttc Migration Guide]

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)