fontisan 0.4.6 → 0.4.8

data/docs/SVG_TO_GLYF.adoc

@@ -0,0 +1,118 @@
+= SVG to Glyph Guide
+
+== General
+
+`Fontisan::SvgToGlyf` converts SVG path data — as produced by ucode's
+code-chart extraction — into `Ufo::Glyph` objects that feed directly
+into the UFO → TTF/OTF compile pipeline.
+
+SvgToGlyf emits cubic Bezier contours (matching UFO/PostScript
+conventions). The cubic-to-quadratic conversion and winding-order
+correction happen later, in `Ufo::Compile::Filters::CubicToQuadratic`
+and `ReverseContourDirection`, when the glyph is compiled to TTF.
+
+== API
+
+[cols="2,3", options="header"]
+|===
+| Method | Purpose
+
+| `SvgToGlyf.convert(path_data, upm:, codepoint:, name:, viewbox:, transform:)`
+| Convert a single SVG path `d` string into a `Ufo::Glyph`
+
+| `SvgToGlyf.from_svg_file(file_path, upm:, codepoint:)`
+| Convert one `.svg` file into a `Ufo::Glyph`
+
+| `SvgToGlyf.from_directory(dir, upm:)`
+| Convert a directory of `.svg` files into a `Ufo::Font` (one glyph
+  per file)
+|===
+
+The default `upm` is 1000.
+
+== Single path
+
+[source,ruby]
+----
+glyph = Fontisan::SvgToGlyf.convert(
+  "M 0 0 L 500 0 L 500 700 L 0 700 Z",
+  upm: 1000,
+  codepoint: 0x10940,
+)
+# → #<Fontisan::Ufo::Glyph name="uni10940" ...>
+----
+
+== Single file
+
+[source,ruby]
+----
+glyph = Fontisan::SvgToGlyf.from_svg_file("U+10940.svg", upm: 1000)
+----
+
+If the codepoint is not supplied, it is derived from the filename when
+it matches `U+XXXX.svg` or `hexcode.svg`.
+
+== Directory → Font
+
+For batch conversion of a code-chart directory (one SVG per
+codepoint):
+
+[source,ruby]
+----
+font = Fontisan::SvgToGlyf.from_directory(
+  "/tmp/chart-svg/Khitan",
+  upm: 1000,
+)
+Fontisan::Ufo::Compile::TtfCompiler.new(font)
+  .compile(output_path: "Khitan.ttf")
+----
+
+Or feed it directly to the Stitcher:
+
+[source,ruby]
+----
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:khitan, font)
+stitcher.include_range(0x18B00..0x18CFF, from: :khitan, into: :main)
+stitcher.write_to("Khitan.ttf", format: :ttf, subfont: :main)
+----
+
+== SVG subset supported
+
+SvgToGlyf handles the subset of SVG that real chart extractions use:
+
+* Path commands: `M`, `L`, `H`, `V`, `C`, `S`, `Q`, `T`, `A`, `Z`
+  (absolute and lowercase relative variants)
+* `<svg>` `viewBox` and `width`/`height` for coordinate scaling
+* `<g transform="...">` group transforms (matrix, translate, scale,
+  rotate)
+* `<path d="...">` elements
+
+Unsupported SVG features (filters, masks, embedded raster images) are
+ignored. SvgToGlyf is a vector-only converter — for raster emoji, use
+the CBDT/CBLC passthrough path (see link:STITCHER_GUIDE.adoc[Stitcher Guide]).
+
+== Coordinate system
+
+SVG uses a y-down coordinate system; UFO uses y-up. SvgToGlyf flips
+the y-axis using the SVG `viewBox` height so glyphs render right-way-up
+in font rendering contexts. When no `viewBox` is present, the
+`<svg>` `width`/`height` attributes are used as a fallback.
+
+== Namespace layout
+
+[source]
+----
+Fontisan::SvgToGlyf
+├── Path       # SVG path parser → contour builder
+├── Geometry   # AffineTransform, vector math
+├── Document   # <svg> document parsing, viewBox handling
+└── Assembler  # top-level glue: builds Ufo::Glyph / Ufo::Font
+----
+
+== See also
+
+* link:UFO_COMPILATION.adoc[UFO Compilation Guide] — compile converted
+  glyphs to binary fonts
+* link:STITCHER_GUIDE.adoc[Stitcher Guide] — combine converted fonts
+  with other donors

data/docs/UFO_COMPILATION.adoc

@@ -0,0 +1,119 @@
+= UFO Compilation Guide
+
+== General
+
+Fontisan compiles UFO (Unified Font Object) v2/v3 sources into binary
+OpenType fonts — TTF, OTF (CFF1), and OTF2 (CFF2) — entirely in pure
+Ruby. No AFDKO or Python fonttools required.
+
+All compilers live under `Fontisan::Ufo::Compile` and share a common
+`BaseCompiler` orchestrator that emits the required set of OpenType
+tables (head, hhea, maxp, OS/2, name, post, hmtx, cmap, plus an
+optional GPOS kern table when the source has kerning data). Subclasses
+add format-specific outline tables.
+
+== Compilers
+
+[cols="1,1,3", options="header"]
+|===
+| Class | Output | Outline format
+
+| `Ufo::Compile::TtfCompiler`
+| `.ttf`
+| Quadratic Bezier curves in the `glyf` table
+
+| `Ufo::Compile::OtfCompiler`
+| `.otf` (CFF1)
+| Cubic Bezier curves in the `CFF ` table using Type 2 charstrings
+
+| `Ufo::Compile::Otf2Compiler`
+| `.otf` (CFF2)
+| Cubic Bezier curves in the `CFF2` table — modern format, supports
+  variable fonts via blend/vsindex operators
+|===
+
+== Building a single font
+
+[source,ruby]
+----
+require "fontisan"
+
+font = Fontisan::Ufo::Font.open("MyFont.ufo")
+
+# TrueType
+Fontisan::Ufo::Compile::TtfCompiler.new(font)
+  .compile(output_path: "MyFont.ttf")
+
+# OpenType / CFF1
+Fontisan::Ufo::Compile::OtfCompiler.new(font)
+  .compile(output_path: "MyFont.otf")
+
+# OpenType / CFF2 (modern, supports variable fonts)
+Fontisan::Ufo::Compile::Otf2Compiler.new(font)
+  .compile(output_path: "MyFont-CFF2.otf")
+----
+
+== TTF filters
+
+The TTF compiler applies two UFO glyph filters automatically:
+
+1. `CubicToQuadratic` — converts cubic Bezier control points to
+   quadratic. TTF `glyf` only supports quadratic curves; UFO sources
+   typically use cubics (matching PostScript/CFF conventions).
+2. `ReverseContourDirection` — reverses winding order. CFF and TTF
+   use opposite fill conventions (CFF: non-zero wind; TTF: even-odd by
+   default), so contour direction must be flipped.
+
+These filters live under `Ufo::Compile::Filters` and are applied to
+each glyph before serialization to `glyf`.
+
+== Tables emitted
+
+Every compiler emits this shared set:
+
+[cols="1,3", options="header"]
+|===
+| Tag | Purpose
+
+| `head` | Font header (units per em, bounding box, timestamps)
+| `hhea` | Horizontal header (ascender, descender, line gap)
+| `maxp` | Maximum profile (glyph count, point/contour limits)
+| `OS/2` | OS/2 and Windows-specific metrics
+| `name` | Name records (family, subfamily, copyright, etc.)
+| `post` | PostScript name table (glyph names)
+| `hmtx` | Horizontal metrics (advance width, left side bearing)
+| `cmap` | Character to glyph mapping
+| `GPOS` | Optional — present only when the UFO has kerning data
+|===
+
+Format-specific outline tables:
+
+* TTF → `glyf` + `loca`
+* OTF (CFF1) → `CFF `
+* OTF2 (CFF2) → `CFF2`
+
+== GPOS kerning
+
+If the UFO source includes kerning data (`kerning.plist`), the compiler
+emits a `GPOS` table with a pair-positioning lookup (feature `kern`).
+When no kerning is present, no `GPOS` table is written — the file stays
+smaller.
+
+== Round-tripping binary ↔ UFO
+
+To go the other way — extract a UFO from an existing binary font:
+
+[source,ruby]
+----
+ttf = Fontisan::FontLoader.load("MyFont.ttf")
+ufo = Fontisan::Ufo::Convert::FromBinData.convert(ttf)
+Fontisan::Ufo::Writer.new(ufo).write("MyFont.ufo")
+----
+
+== See also
+
+* link:CFF2_SUPPORT.adoc[CFF2 Support Guide] — variable-font blend
+  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

data/docs/cli/index.md

@@ -20,18 +20,6 @@ Always check your font's End User License Agreement (EULA) before processing. Ma
 
 ## Quick Reference
 
-### Font Audit
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `audit` | Comprehensive per-face audit (replaces `otfinfo`) | `fontisan audit font.ttf` |
-
-The `audit` command covers identity, style, metrics, codepoint coverage,
-licensing, hinting, color capabilities, variable-font detail, and
-OpenType layout — and supports collections, `--compare` mode, and
-whole-library `--recursive --summary` mode. See
-[audit](/cli/audit) for details.
-
 ### Font Information Commands
 
 | Command | Description | Example |
@@ -179,19 +167,11 @@ fontisan validate font.ttf --profile production
 
 ### Audit a Font (or Library)
 
-```bash
-# Full per-face audit
-fontisan audit font.ttf
-
-# Diff two fonts (or saved reports)
-fontisan audit --compare baseline.yaml new.ttf
-
-# Whole-library summary
-fontisan audit lib/ --recursive --summary
-
-# Fast inventory pass
-fontisan audit lib/ --recursive --summary --brief
-```
+The `audit` and `ucd` commands have been removed from fontisan. The
+audit/UCD subsystem moved to the
+[ucode](https://github.com/fontist/ucode) gem. For per-face font
+metadata, use [`info`](/cli/info); for pass/fail quality checks, use
+[`validate`](/cli/validate).
 
 ### Export Font Data
 
@@ -210,9 +190,6 @@ fontisan export font.ttf --format ttx --tables head,name,cmap
 
 Detailed documentation for each command:
 
-### Font Audit
-- [audit](/cli/audit) — Comprehensive per-face audit (replaces `otfinfo`); supports collections, compare, library summary
-
 ### Font Information
 - [info](/cli/info) — Extract font metadata and properties (includes brief mode)
 - [ls](/cli/ls) — List fonts in collections

data/docs/index.md

@@ -18,8 +18,6 @@ hero:
       link: /guide/migrations/fonttools
 
 features:
-  - title: "🔍 Font Audit"
-    details: Comprehensive per-face audit (replaces otfinfo) — identity, style, metrics, coverage, licensing, hinting, color, variation, OpenType layout, UCD/CLDR aggregation, compare, and library-summary modes.
   - title: "🔄 Font Conversion"
     details: Convert between TTF, OTF, WOFF, WOFF2, Type 1 (PFB/PFA), and SVG formats with curve conversion and optimization.
   - title: "✅ Font Validation"

data/lib/fontisan/cli.rb

@@ -25,9 +25,6 @@ module Fontisan
                          desc: "Suppress non-error output",
                          aliases: "-q"
 
-    desc "cldr", "Manage local CLDR cache (subcommands)", hide: true
-    subcommand "cldr", CldrCli
-
     desc "ufo", "UFO source operations (build, convert, validate)"
     subcommand "ufo", Fontisan::Ufo::Cli
 
@@ -211,10 +208,12 @@ module Fontisan
     end
 
     desc "convert FONT_FILE", "Convert font to different format"
-    option :to, type: :string, required: true,
-                desc: "Target format: ttf, otf, type1, t1, ttc, otc, dfont, svg, " \
+    option :to, type: :array, required: true,
+                desc: "Target format(s): ttf, otf, type1, t1, ttc, otc, dfont, svg, " \
                       "woff (zlib — works on all browsers incl. legacy), " \
-                      "woff2 (Brotli — ~30% smaller, modern browsers only)",
+                      "woff2 (Brotli — ~30% smaller, modern browsers only). " \
+                      "Pass multiple times (--to woff --to woff2) or comma-separated " \
+                      "(--to woff,woff2) for multi-format output.",
                 aliases: "-t"
     option :output, type: :string,
                     desc: "Output file path (required unless --show-options)",
@@ -361,7 +360,7 @@ module Fontisan
 
       # Handle --show-options
       if options[:show_options]
-        show_recommended_options(source_format, options[:to])
+        show_recommended_options(source_format, options[:to].is_a?(Array) ? options[:to].first : options[:to])
         return
       end
 
@@ -371,7 +370,8 @@ module Fontisan
       end
 
       # Build ConversionOptions
-      conv_options = build_conversion_options(source_format, options[:to],
+      conv_options = build_conversion_options(source_format,
+                                              Array(options[:to]).first,
                                               options)
 
       # Build instance coordinates from axis options
@@ -573,6 +573,27 @@ module Fontisan
       exit command.run
     end
 
+    desc "validate-collection PATH",
+         "Validate a TTC/OTC/dfont (face count, glyph cap, cmap union)"
+    option :expected_faces, type: :numeric,
+                            desc: "Required face count"
+    option :max_glyphs, type: :numeric, default: Fontisan::Commands::ValidateCollectionCommand::DEFAULT_MAX_GLYPHS,
+                        desc: "Per-face glyph cap"
+    option :expected_cmap_union, type: :numeric,
+                                 desc: "Minimum cmap union size across all faces"
+    def validate_collection(path)
+      cmd = Commands::ValidateCollectionCommand.new(
+        input: path,
+        expected_faces: options[:expected_faces],
+        max_glyphs: options[:max_glyphs],
+        expected_cmap_union: options[:expected_cmap_union],
+      )
+      exit cmd.run
+    rescue ArgumentError => e
+      warn "ERROR: #{e.message}"
+      exit 1
+    end
+
     desc "version", "Display version information"
     # Display the Fontisan version.
     def version

data/lib/fontisan/collection/reader/stats.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Collection
+    class Reader
+      # Snapshot of one face's headline metrics. Pure value object —
+      # no methods beyond accessors. Separate file from {Reader} so
+      # the Stats struct can be referenced without pulling in the
+      # full Reader (and its FontLoader dependency).
+      #
+      # @!attribute [r] index
+      #   @return [Integer] 0-based face index inside the collection
+      # @!attribute [r] glyph_count
+      #   @return [Integer] face's maxp.numGlyphs
+      # @!attribute [r] codepoint_count
+      #   @return [Integer] count of keys in face's cmap unicode_mappings
+      # @!attribute [r] sfnt_version
+      #   @return [Integer] face sfnt version (0x00010000 for TTF, 0x4F54544F for OTF)
+      Stats = Struct.new(:index, :glyph_count, :codepoint_count, :sfnt_version,
+                         keyword_init: true)
+    end
+  end
+end

data/lib/fontisan/collection/reader.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Collection
+    # Read-only counterpart to {Builder}. Opens an existing TTC/OTC/dfont
+    # and exposes per-face metadata (glyph count, codepoint count, sfnt
+    # version) and the cmap union across all faces.
+    #
+    # Delegates header parsing to {FontLoader} — never hand-rolls the
+    # TTC header bytes (that would duplicate BaseCollection.from_file
+    # and only handle TTC/OTC, not dfont).
+    #
+    # @example Per-face glyph counts
+    #   reader = Collection::Reader.open("family.ttc")
+    #   reader.stats.map { |s| [s.index, s.glyph_count] }
+    #
+    # @example Cmap union
+    #   Collection::Reader.open("family.otc").cmap_union.size
+    class Reader
+      autoload :Stats, "fontisan/collection/reader/stats"
+
+      # @!attribute [r] path
+      #   @return [String] the file path this reader was opened with
+      attr_reader :path
+
+      # Collection formats this reader accepts. Single source of truth —
+      # matches {FontLoader::COLLECTION_CLASSES}.
+      FORMATS = %i[ttc otc dfont].freeze
+
+      # @param path [String] path to a TTC/OTC/dfont file
+      # @raise [ArgumentError] if the file is not a recognized collection
+      def initialize(path)
+        @path = path
+        detected = FontLoader.detect_format(path)
+        unless FORMATS.include?(detected)
+          raise ArgumentError,
+                "#{path} is not a TTC/OTC/dfont (detected: #{detected.inspect})"
+        end
+
+        @collection = FontLoader.load_collection(path)
+      end
+
+      # Convenience constructor.
+      # @param path [String]
+      # @return [Reader]
+      def self.open(path)
+        new(path)
+      end
+
+      # @return [Integer] number of faces in the collection
+      def face_count
+        @collection.num_fonts
+      end
+
+      # Yields each face as a loaded TTF/OTF font. Without a block,
+      # returns an Enumerator (so callers can chain +each_with_index+).
+      # The Enumerator's size is set to +face_count+ so size-based
+      # assertions work without consuming it.
+      #
+      # @yieldparam face [TrueTypeFont, OpenTypeFont]
+      # @return [Enumerator, void]
+      def each_face
+        return enum_for(:each_face) { face_count } unless block_given?
+
+        face_count.times { |i| yield FontLoader.load(@path, font_index: i) }
+      end
+
+      # @return [Array<Stats>] one Stats per face, in face-index order
+      def stats
+        each_face.map.with_index do |face, i|
+          Stats.new(
+            index: i,
+            glyph_count: face.table("maxp")&.num_glyphs || 0,
+            codepoint_count: (face.table("cmap")&.unicode_mappings || {}).size,
+            sfnt_version: face.header.sfnt_version,
+          )
+        end
+      end
+
+      # Union of every face's cmap keys.
+      #
+      # @return [Set<Integer>]
+      def cmap_union
+        each_face.with_object(Set.new) do |face, union|
+          union.merge((face.table("cmap")&.unicode_mappings || {}).keys)
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/collection/writer.rb

@@ -19,6 +19,10 @@ module Fontisan
       VERSION_1_0_MAJOR = 1
       VERSION_1_0_MINOR = 0
 
+      # TTC version 2.0 (major=2, minor=0) — supports DSIG reference
+      VERSION_2_0_MAJOR = 2
+      VERSION_2_0_MINOR = 0
+
       # Initialize writer
       #
       # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Source fonts
@@ -91,12 +95,7 @@ module Fontisan
       #
       # @return [String] TTC header binary
       def write_ttc_header
-        [
-          TTC_TAG,                  # char[4] - tag
-          VERSION_1_0_MAJOR,        # uint16 - major version
-          VERSION_1_0_MINOR,        # uint16 - minor version
-          @fonts.size, # uint32 - number of fonts
-        ].pack("a4 n n N")
+        [TTC_TAG, VERSION_1_0_MAJOR, VERSION_1_0_MINOR, @fonts.size].pack("a4nnN")
       end
 
       # Write offset table

data/lib/fontisan/collection.rb

@@ -7,6 +7,7 @@ module Fontisan
     autoload :Builder, "fontisan/collection/builder"
     autoload :DfontBuilder, "fontisan/collection/dfont_builder"
     autoload :OffsetCalculator, "fontisan/collection/offset_calculator"
+    autoload :Reader, "fontisan/collection/reader"
     autoload :SharedLogic, "fontisan/collection/shared_logic"
     autoload :TableAnalyzer, "fontisan/collection/table_analyzer"
     autoload :TableDeduplicator, "fontisan/collection/table_deduplicator"